gitnexus 1.6.9 → 1.6.10-rc.10

package/dist/core/ingestion/utils/line-base.js

@@ -0,0 +1,20 @@
+/**
+ * Convert a 1-based source line number to the 0-based convention used by
+ * GraphNode `startLine`/`endLine`.
+ *
+ * The graph layer stores line numbers 0-based (tree-sitter `startPosition.row`),
+ * and this is load-bearing: the taint/PDG/CFG join and the MCP consumers all add
+ * `+ 1` to recover 1-based (see `summary-harvest-driver.ts` — "Function/Method
+ * node startLine is 0-based"). Most emitters get 0-based for free from
+ * tree-sitter. The exceptions are the regex-based COBOL/JCL processors (their
+ * parsers use `lineNum = i + 1`) and the scope-capture path (`Capture` ranges
+ * are 1-based per RFC §2.1). Those must convert to 0-based when they build a
+ * graph node, or the exact-content slice in `csv-generator.ts` drops the
+ * symbol's declaration line (#2379) and reported line numbers are off (#2377).
+ *
+ * Apply this ONLY at the graph-node `startLine:`/`endLine:` assignment. The
+ * parser-internal 1-based values (`.line`, `prog.startLine`) stay 1-based —
+ * they feed `L${line}` node/edge IDs and line-range containment checks that
+ * must not shift. The clamp guards degenerate inputs (line 0 / empty files).
+ */
+export const toZeroBasedLine = (oneBasedLine) => Math.max(0, oneBasedLine - 1);

package/dist/core/ingestion/utils/symbol-labels.d.ts

@@ -0,0 +1,21 @@
+import type { NodeLabel } from '../../../_shared/index.js';
+/**
+ * Graph-node labels that represent a resolvable code symbol — a definition with
+ * its own source span (function, type, member, module-like container).
+ *
+ * These get EXACT source-span content in the FTS index: `csv-generator.ts`
+ * slices exactly `[startLine, endLine]` for them (no ±2 padding), while every
+ * other label keeps the context window. That exactness depends on the 0-based
+ * `startLine`/`endLine` invariant enforced by `line-base.ts` — the slice is only
+ * correct because all emitters store 0-based lines. Keep the two together.
+ *
+ * Single source of truth so the set can't silently drift the way the inline copy
+ * did in #2379.
+ *
+ * NOTE: `group/extractors/manifest-extractor.ts`'s `CUSTOM_CONTRACT_RESOLVE_QUERY`
+ * carries a near-identical hand-list that is intentionally a SUBSET — it excludes
+ * `Namespace`, `Variable`, `Module`. Unifying the two needs a contract-resolution
+ * behavior check (would widen which nodes resolve as contract symbols), so it is
+ * deliberately left separate for now.
+ */
+export declare const SYMBOL_NODE_LABELS: ReadonlySet<NodeLabel>;

package/dist/core/ingestion/utils/symbol-labels.js

@@ -0,0 +1,45 @@
+/**
+ * Graph-node labels that represent a resolvable code symbol — a definition with
+ * its own source span (function, type, member, module-like container).
+ *
+ * These get EXACT source-span content in the FTS index: `csv-generator.ts`
+ * slices exactly `[startLine, endLine]` for them (no ±2 padding), while every
+ * other label keeps the context window. That exactness depends on the 0-based
+ * `startLine`/`endLine` invariant enforced by `line-base.ts` — the slice is only
+ * correct because all emitters store 0-based lines. Keep the two together.
+ *
+ * Single source of truth so the set can't silently drift the way the inline copy
+ * did in #2379.
+ *
+ * NOTE: `group/extractors/manifest-extractor.ts`'s `CUSTOM_CONTRACT_RESOLVE_QUERY`
+ * carries a near-identical hand-list that is intentionally a SUBSET — it excludes
+ * `Namespace`, `Variable`, `Module`. Unifying the two needs a contract-resolution
+ * behavior check (would widen which nodes resolve as contract symbols), so it is
+ * deliberately left separate for now.
+ */
+export const SYMBOL_NODE_LABELS = new Set([
+    'Function',
+    'Method',
+    'Class',
+    'Interface',
+    'CodeElement',
+    'Struct',
+    'Enum',
+    'Macro',
+    'Typedef',
+    'Union',
+    'Namespace',
+    'Trait',
+    'Impl',
+    'TypeAlias',
+    'Const',
+    'Static',
+    'Variable',
+    'Property',
+    'Record',
+    'Delegate',
+    'Annotation',
+    'Constructor',
+    'Template',
+    'Module',
+]);

package/dist/core/ingestion/workers/parse-worker.d.ts

@@ -113,6 +113,21 @@ export interface ExtractedDecoratorRoute {
      * participate in `include_router(prefix=...)` joining.
      */
     decoratorReceiver?: string;
+    /**
+     * Raw text of a non-literal decorator path argument (`#2391`), e.g.
+     * `API_V1_WIDGETS_GET` or `API_V1 + "/widgets"`. Present only when the
+     * decorator's first argument was NOT a string literal, in which case
+     * `routePath` is empty and parse-impl resolves the constant cross-file (or
+     * drops the route on failure). Absent for ordinary string-literal routes.
+     */
+    routePathExpr?: string;
+    /**
+     * Parsed operand list for {@link routePathExpr} — an identifier reference or a
+     * `+`-concatenation, in the {@link Operand} shape the constant resolver folds.
+     * `undefined` when the expression was not a foldable string form (e.g. an
+     * attribute access), in which case the route is dropped at resolution.
+     */
+    routePathOperands?: Operand[];
     /**
      * FastAPI `app.include_router(prefix='/x')` prefix that applies to
      * this route. Filled by parse-impl after cross-file aggregation; the
@@ -131,6 +146,17 @@ export interface ExtractedDecoratorRoute {
      */
     handlerName?: string;
 }
+/**
+ * One Python file's module-level string constants (#2391), used by parse-impl to
+ * resolve non-literal decorator route paths cross-file. `constants` is the
+ * `Map`-based {@link ModuleConstants} shape — it survives the worker
+ * `postMessage` boundary (structured clone) and the parse cache
+ * (`mapReplacer`/`mapReviver`) without conversion.
+ */
+export interface ExtractedModuleConstants {
+    filePath: string;
+    constants: ModuleConstants;
+}
 export interface ExtractedToolDef {
     filePath: string;
     toolName: string;
@@ -211,6 +237,13 @@ export interface ParseWorkerResult {
      * predate the field; consumers must guard with `if (… ?? [])`).
      */
     routerModuleAliases?: ExtractedRouterModuleAlias[];
+    /**
+     * Per-file Python module-level string constants (#2391). parse-impl aggregates
+     * these into a repo-wide, file-path-keyed map and resolves each decorator
+     * route's non-literal path expression against it. Optional for cache backward
+     * compatibility (older entries predate the field; consumers guard with `?? []`).
+     */
+    moduleConstants?: ExtractedModuleConstants[];
     toolDefs: ExtractedToolDef[];
     ormQueries: ExtractedORMQuery[];
     constructorBindings: FileConstructorBindings[];
@@ -256,3 +289,4 @@ export interface ParseWorkerInput {
  * Appends results to the provided array (avoids allocation when no matches).
  */
 export declare function extractORMQueries(filePath: string, content: string, out: ExtractedORMQuery[]): void;
+import { type ModuleConstants, type Operand } from '../route-extractors/python-const-resolver.js';

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

@@ -751,6 +751,7 @@ 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';
+import { extractPythonModuleConstants, parseConstOperands, } from '../route-extractors/python-const-resolver.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
@@ -986,6 +987,12 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             if (captureMap['decorator'] && captureMap['decorator.name']) {
                 const decoratorName = captureMap['decorator.name'].text;
                 const decoratorArg = captureMap['decorator.arg']?.text;
+                // #2391: the first positional arg captured as either a string node
+                // (`arg_str`, present even for the empty-string literal `""` which has no
+                // `string_content`) or a non-literal expression (`arg_expr`: an
+                // identifier or a `+`-concatenation).
+                const decoratorArgStr = captureMap['decorator.arg_str'];
+                const decoratorArgExpr = captureMap['decorator.arg_expr'];
                 const decoratorReceiver = captureMap['decorator.receiver']?.text;
                 const decoratorNode = captureMap['decorator'];
                 // Store by the decorator's end line — the definition follows immediately after
@@ -994,19 +1001,39 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                     arg: decoratorArg,
                 });
                 if (ROUTE_DECORATOR_NAMES.has(decoratorName)) {
-                    const routePath = decoratorArg || '';
                     const method = decoratorName.replace('Mapping', '').toUpperCase();
                     const httpMethod = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].includes(method)
                         ? method
                         : 'GET';
-                    result.decoratorRoutes.push({
+                    const base = {
                         filePath: file.path,
-                        routePath,
                         httpMethod,
                         decoratorName,
                         lineNumber: decoratorNode.startPosition.row + lineOffset,
                         ...(decoratorReceiver ? { decoratorReceiver } : {}),
-                    });
+                    };
+                    if (decoratorArgStr) {
+                        // String-literal path (the fast path, unchanged). Empty-string
+                        // literal `""` has no `string_content` → `decoratorArg` undefined →
+                        // routePath '' (a valid path under an APIRouter prefix).
+                        result.decoratorRoutes.push({ ...base, routePath: decoratorArg ?? '' });
+                    }
+                    else if (decoratorArgExpr) {
+                        // #2391 non-literal path (imported/composed constant). Emit the raw
+                        // expression + its operands for cross-file resolution in parse-impl;
+                        // `routePath` stays empty until resolved (or the route is dropped).
+                        const operands = decoratorArgExpr.type === 'identifier'
+                            ? [{ kind: 'ref', name: decoratorArgExpr.text }]
+                            : parseConstOperands(decoratorArgExpr);
+                        result.decoratorRoutes.push({
+                            ...base,
+                            routePath: '',
+                            routePathExpr: decoratorArgExpr.text,
+                            ...(operands ? { routePathOperands: operands } : {}),
+                        });
+                    }
+                    // Otherwise the first arg is absent or an unsupported shape
+                    // (attribute access, call, …) → skip; never a phantom `POST /`.
                 }
                 // MCP/RPC tool detection: @mcp.tool(), @app.tool(), @server.tool()
                 if (decoratorName === 'tool') {
@@ -1839,6 +1866,14 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         // came from a `@router.<verb>` decorator. Python-only.
         if (language === SupportedLanguages.Python) {
             extractFastAPIRouterBindings(file.path, parseContent, result.routerIncludes, result.routerImports, (result.routerModuleAliases ??= []), (result.routerConstructorPrefixes ??= []));
+            // #2391: harvest module-level string constants + from-imports so parse-impl
+            // can resolve non-literal decorator route paths cross-file. Only emit for
+            // files that carry something resolvable (a constant definition or an import
+            // binding) to keep the aggregate bounded on large repos.
+            const constants = extractPythonModuleConstants(tree);
+            if (constants.literals.size > 0 || constants.exprs.size > 0 || constants.imports.size > 0) {
+                (result.moduleConstants ??= []).push({ filePath: file.path, constants });
+            }
         }
         // Language-specific decorator route extraction via provider hook.
         // The provider's extractDecoratorRoutes walks the AST for framework-specific

package/dist/core/ingestion/workers/result-merge.js

@@ -32,6 +32,10 @@ export const mergeResult = (target, src) => {
         target.routerModuleAliases ??= [];
         appendAll(target.routerModuleAliases, src.routerModuleAliases);
     }
+    if (src.moduleConstants) {
+        target.moduleConstants ??= [];
+        appendAll(target.moduleConstants, src.moduleConstants);
+    }
     if (src.springTypes) {
         target.springTypes ??= [];
         appendAll(target.springTypes, src.springTypes);

package/dist/core/lbug/csv-generator.js

@@ -17,6 +17,7 @@ import path from 'path';
 import { NODE_TABLES } from './schema.js';
 import { RelPairRouter } from './rel-pair-routing.js';
 import { parseTruthyEnv } from '../ingestion/utils/env.js';
+import { SYMBOL_NODE_LABELS } from '../ingestion/utils/symbol-labels.js';
 import { applyCjkSegmentationIfEnabled } from '../search/cjk-segmentation.js';
 /**
  * Deterministic output ordering — optional (out-of-core / windowed-resolve
@@ -187,6 +188,10 @@ class FileContentCache {
 export const normalizeFtsText = (text) => text.replace(/[\r\n\t]+/g, ' ');
 /** Composes both FTS-text transforms for the `description` column — one place for the six emission sites below to call, instead of repeating the composition. */
 const formatFtsDescription = (description) => normalizeFtsText(applyCjkSegmentationIfEnabled(description));
+// Labels that get exact source-span content (no ±2 window). Single source of
+// truth in `symbol-labels.ts` — see there for why the exactness depends on the
+// 0-based line invariant. Kept as a named alias to read intent at the use site.
+const EXACT_SYMBOL_CONTENT_LABELS = SYMBOL_NODE_LABELS;
 const extractContent = async (node, contentCache) => {
     const filePath = node.properties.filePath;
     const content = await contentCache.get(filePath);
@@ -209,8 +214,9 @@ const extractContent = async (node, contentCache) => {
     if (startLine === undefined || endLine === undefined)
         return '';
     const lines = content.split('\n');
-    const start = Math.max(0, startLine - 2);
-    const end = Math.min(lines.length - 1, endLine + 2);
+    const exactSymbolContent = EXACT_SYMBOL_CONTENT_LABELS.has(node.label);
+    const start = Math.max(0, exactSymbolContent ? startLine : startLine - 2);
+    const end = Math.min(lines.length - 1, exactSymbolContent ? endLine : endLine + 2);
     const snippet = lines.slice(start, end + 1).join('\n');
     const MAX_SNIPPET = 5000;
     const capped = snippet.length > MAX_SNIPPET ? snippet.slice(0, MAX_SNIPPET) + '\n... [truncated]' : snippet;

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

@@ -0,0 +1,67 @@
+export type ExtensionLoadErrorKind = 'missing_file' | 'corrupt_file' | 'missing_dependency' | 'unknown';
+export interface ExtensionLoadDiagnosis {
+    readonly kind: ExtensionLoadErrorKind;
+    /** Actionable, literal-English remedy suited to the class. */
+    readonly remedy: string;
+}
+/**
+ * On-disk file corruption / wrong-platform. FORCE INSTALL re-downloads.
+ * Kept byte-identical to `FILE_CORRUPTION_SIGNATURES` in
+ * scripts/install-duckdb-extension.mjs (that `.mjs` cannot import this `.ts`;
+ * the duplication is deliberate — the two serve different call sites). Note
+ * `/not a valid/i` already covers Windows error 193 ("is not a valid Win32
+ * application"), so a truncated Windows download is caught here, before the
+ * missing-dependency branch.
+ */
+export declare const FILE_CORRUPTION_SIGNATURES: readonly RegExp[];
+/**
+ * Classify a collapsed LadybugDB LOAD error. Order is most-specific-first and is
+ * load-bearing: corrupt-file is tested before missing-dependency so a truncated
+ * Windows download (error 193, matched by `/not a valid/i`) routes to
+ * FORCE-reinstall rather than to the runtime-install remedy.
+ */
+export declare function classifyExtensionLoadError(reason: string | undefined | null): ExtensionLoadDiagnosis;
+/** Well-formedness of the extension binary for the host platform + arch. */
+export type ExtensionBinaryState = 'absent' | 'corrupt' | 'valid' | 'indeterminate';
+/**
+ * Pull the extension file path out of lbug's load error. lbug's wrapper is
+ * English regardless of OS language — `Failed to load library: {path} which is
+ * needed by extension: {name}` (real lbug), or the quoted `Failed to load
+ * library '{path}': {reason}` variant — so the path is recoverable in any locale.
+ * Only paths ending in `.lbug_extension` are accepted, so a regex misfire can
+ * never point the inspector at an arbitrary file.
+ */
+export declare function extractExtensionPath(reason: string | undefined | null): string | null;
+/**
+ * A structural verdict on a binary header. `indeterminate` means the probe could
+ * not prove validity OR corruption from what it read (e.g. the PE header sits past
+ * the BINARY_HEADER_BYTES window) — the caller defers to the string classifier
+ * rather than assert a false verdict.
+ */
+type HeaderVerdict = 'valid' | 'corrupt' | 'indeterminate';
+/**
+ * Decide whether a binary header is a well-formed shared library for the given
+ * platform + architecture — using only the file's structure, no localized text.
+ * Pure and injectable (platform/arch as params) so every format+arch combination
+ * is unit-testable regardless of the host it runs on.
+ */
+export declare function classifyBinaryHeader(buf: Buffer, bytesRead: number, platform: NodeJS.Platform, arch: string): HeaderVerdict;
+/**
+ * Best-effort language-independent inspection of the extension file. Reads the
+ * header and classifies it; never throws — a missing file is `absent`, an
+ * unreadable one is `indeterminate`.
+ */
+export declare function inspectExtensionBinary(extensionPath: string | null | undefined): ExtensionBinaryState;
+/**
+ * Diagnose a LadybugDB load failure, preferring a LANGUAGE-INDEPENDENT structural
+ * check of the extension binary over the localized error text:
+ *   - file absent             → missing_file
+ *   - present but malformed    → corrupt_file       (bad magic / wrong architecture)
+ *   - present and well-formed   → missing_dependency (a valid binary the loader rejected)
+ * The path comes from lbug's own English wrapper, so this holds in any OS display
+ * language. When the file cannot be located or read, it falls back to the string
+ * classifier (which still carries the language-independent hedged fallback). This
+ * is the entry point every surface should call.
+ */
+export declare function diagnoseExtensionLoad(reason: string | undefined | null): ExtensionLoadDiagnosis;
+export {};

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

@@ -0,0 +1,320 @@
+/**
+ * Classify a LadybugDB `LOAD EXTENSION` failure into one of four actionable
+ * classes and produce an accurate, literal-English remedy.
+ *
+ * Background (#2374): PR #2375 made the real LadybugDB LOAD error visible
+ * (instead of a false "not pre-installed" message). The rc.4 reproduction then
+ * showed the remaining defect — on Windows the extension file downloads and
+ * INSTALLs fine, but `LoadLibrary` fails with error 126 ("the specified module
+ * could not be found" / `找不到指定的模块`) because the extension dynamically
+ * imports OpenSSL 3 / MSVC 14 DLLs that ship nowhere. For that class, telling
+ * the user to reinstall/redownload is wrong — the file is fine; a *runtime
+ * dependency* is missing. This module decides which class an error is so each
+ * surface (doctor, --repair-fts, the analyze degrade warning, and
+ * ftsDegradedWarning) can emit the right remedy instead of a one-size-fits-all
+ * "reinstall over the network".
+ *
+ * `classifyExtensionLoadError` is pure string logic — no `@ladybugdb/core`
+ * import, no filesystem — which keeps `native-check.ts` free of a static lbug
+ * dependency. `diagnoseExtensionLoad` layers a LANGUAGE-INDEPENDENT structural
+ * check on top: it pulls the extension's file path out of lbug's own (English)
+ * wrapper and inspects the binary header directly (PE/ELF/Mach-O magic +
+ * architecture), so corrupt-vs-valid is decided by the file itself, not by the
+ * localized OS error tail. It reads the file (node:fs core module only, still no
+ * lbug) and never throws — any read failure degrades to the string classifier.
+ */
+import { closeSync, openSync, readSync } from 'node:fs';
+/** LadybugDB says the extension file was never installed. INSTALL can heal it. */
+const MISSING_FILE_SIGNATURES = [
+    /has not been installed/i,
+    /not been installed/i,
+];
+/**
+ * On-disk file corruption / wrong-platform. FORCE INSTALL re-downloads.
+ * Kept byte-identical to `FILE_CORRUPTION_SIGNATURES` in
+ * scripts/install-duckdb-extension.mjs (that `.mjs` cannot import this `.ts`;
+ * the duplication is deliberate — the two serve different call sites). Note
+ * `/not a valid/i` already covers Windows error 193 ("is not a valid Win32
+ * application"), so a truncated Windows download is caught here, before the
+ * missing-dependency branch.
+ */
+// Exported so a parity test can assert this stays byte-identical to the copy in
+// scripts/install-duckdb-extension.mjs (that `.mjs` cannot import this `.ts`), #2383 F5b.
+export const FILE_CORRUPTION_SIGNATURES = [
+    /invalid elf/i,
+    /file too short/i,
+    /not a valid/i,
+    /bad magic/i,
+    /wrong architecture/i,
+    /mach-o/i,
+    /truncat/i,
+];
+/**
+ * A *transitive dependency* of the extension is missing — the file loaded far
+ * enough to be found, but a library it needs is absent. Reinstalling the
+ * extension is a no-op for this class.
+ *
+ * WINDOWS CATCH-ALL GUARD (adversarial review): LadybugDB wraps *every* Windows
+ * load failure in `Failed to load library … which is needed by extension`, so
+ * that generic wrapper must NOT be sufficient — otherwise error 127 (wrong
+ * OpenSSL minor / unresolved procedure), 5 (AV/permission lock), and 1114
+ * (dependency DllMain failure) would all be mislabeled `missing_dependency` and
+ * told to install a runtime, the opposite of their real fix. We key strictly on
+ * the specific error-126 tail. Linux/macOS loaders name the missing library
+ * directly, so their signals are unambiguous.
+ *
+ * Localized Windows tails we do not enumerate (French, German, Japanese, …) and
+ * mojibake renderings of the Chinese text won't match here — but they still
+ * carry lbug's language-independent `Failed to load library` wrapper, so they
+ * are caught by the hedged fallback (LOAD_FAILURE_WRAPPER) with a non-committal
+ * remedy, never a wrong confident "reinstall" instruction.
+ */
+const WINDOWS_MISSING_DEPENDENCY_SIGNATURES = [
+    /找不到指定的模块/,
+    /specified module could not be found/i,
+];
+const POSIX_MISSING_DEPENDENCY_SIGNATURES = [
+    /cannot open shared object file/i, // Linux ld.so
+    /image not found/i, // macOS dyld
+    /library not loaded/i, // macOS dyld
+];
+/**
+ * LadybugDB's own English wrapper for a dlopen/LoadLibrary failure
+ * (extension.cpp: `Failed to load library: {path} which is needed by extension:
+ * {name}`). It is emitted for EVERY extension load failure regardless of the OS
+ * display language — the only localized part is the OS-error tail after it. So
+ * it is the language-independent fallback signal once the specific tails miss: a
+ * French/German/Japanese Windows 126 has a localized tail we cannot enumerate,
+ * but it still carries this wrapper. See HEDGED_LOAD_FAILURE_REMEDY.
+ */
+const LOAD_FAILURE_WRAPPER = /failed to load library/i;
+const MISSING_FILE_REMEDY = 'The FTS extension is not installed. Re-run with network access and ' +
+    'GITNEXUS_LBUG_EXTENSION_INSTALL=auto (or `gitnexus analyze --repair-fts`) to download it.';
+const CORRUPT_FILE_REMEDY = 'The FTS extension file is present but unreadable (corrupt, truncated, or built for another ' +
+    'platform). Re-download it with network access and GITNEXUS_LBUG_EXTENSION_INSTALL=auto ' +
+    '(`gitnexus analyze --repair-fts`).';
+// Single source of truth for the VC++ runtime-install pointer, shared by the
+// Windows-126 and structural missing-dependency remedies so the name/URL cannot
+// drift between them (#2383 F5).
+const VC_REDIST_INSTALL_HINT = 'the Microsoft Visual C++ 2015-2022 Redistributable (x64) from ' +
+    'https://aka.ms/vs/17/release/vc_redist.x64.exe';
+// MSVC-first per DuckDB's canonical answer for this exact error; OpenSSL second.
+const WINDOWS_MISSING_DEPENDENCY_REMEDY = 'The FTS extension is present but a required runtime library is missing (Windows error 126). ' +
+    'Reinstalling the extension will NOT help. Install ' +
+    VC_REDIST_INSTALL_HINT +
+    '; if the error persists, the extension also needs OpenSSL 3 ' +
+    '(libcrypto-3-x64.dll / libssl-3-x64.dll) on the DLL search path.';
+const POSIX_MISSING_DEPENDENCY_REMEDY = 'The FTS extension is present but a shared library it depends on could not be loaded (named in ' +
+    'the error above). Reinstalling the extension will NOT help — install that library or add it to ' +
+    'your loader search path.';
+// Language-independent fallback: we know the extension failed to load, but the
+// OS-error tail is in a locale we did not enumerate, so we cannot say which class
+// it is. Hedge honestly — point at the user's own localized error and give both
+// branches — rather than confidently prescribing the wrong single fix. The clean
+// long-term fix is upstream: have LadybugDB include the numeric GetLastError/errno
+// in the message (as it already does elsewhere), so this becomes a code match.
+const HEDGED_LOAD_FAILURE_REMEDY = 'The FTS extension file was found but could not be loaded — see the "Error:" text above (shown ' +
+    "in your system's language). Reinstalling usually will not help. If it names a missing module or " +
+    'library, install the required runtime (on Windows: the Microsoft Visual C++ 2015-2022 ' +
+    'Redistributable x64 and OpenSSL 3); if it names a corrupt or invalid file, run ' +
+    '`gitnexus analyze --repair-fts` to re-download.';
+const UNKNOWN_REMEDY = 'The FTS extension failed to load for an unrecognized reason. Run `gitnexus doctor` for live ' +
+    'FTS status and verify the extension file and platform.';
+const matchesAny = (reason, signatures) => signatures.some((re) => re.test(reason));
+/**
+ * Classify a collapsed LadybugDB LOAD error. Order is most-specific-first and is
+ * load-bearing: corrupt-file is tested before missing-dependency so a truncated
+ * Windows download (error 193, matched by `/not a valid/i`) routes to
+ * FORCE-reinstall rather than to the runtime-install remedy.
+ */
+export function classifyExtensionLoadError(reason) {
+    const text = reason ?? '';
+    if (matchesAny(text, MISSING_FILE_SIGNATURES)) {
+        return { kind: 'missing_file', remedy: MISSING_FILE_REMEDY };
+    }
+    if (matchesAny(text, FILE_CORRUPTION_SIGNATURES)) {
+        return { kind: 'corrupt_file', remedy: CORRUPT_FILE_REMEDY };
+    }
+    if (matchesAny(text, WINDOWS_MISSING_DEPENDENCY_SIGNATURES)) {
+        return { kind: 'missing_dependency', remedy: WINDOWS_MISSING_DEPENDENCY_REMEDY };
+    }
+    if (matchesAny(text, POSIX_MISSING_DEPENDENCY_SIGNATURES)) {
+        return { kind: 'missing_dependency', remedy: POSIX_MISSING_DEPENDENCY_REMEDY };
+    }
+    // Language-independent fallback: the extension demonstrably failed to load
+    // (lbug's English wrapper is present) but the localized OS tail matched no
+    // specific class. Treat as a dependency/runtime load failure with a hedged
+    // remedy — strictly better than the generic `unknown` for non-English hosts,
+    // and it never prescribes the wrong fix.
+    if (LOAD_FAILURE_WRAPPER.test(text)) {
+        return { kind: 'missing_dependency', remedy: HEDGED_LOAD_FAILURE_REMEDY };
+    }
+    return { kind: 'unknown', remedy: UNKNOWN_REMEDY };
+}
+const STRUCTURAL_MISSING_DEPENDENCY_REMEDY = 'The FTS extension file is valid, so the failure is a missing or incompatible runtime dependency, ' +
+    'not the extension itself — reinstalling will NOT help. On Windows, install ' +
+    VC_REDIST_INSTALL_HINT +
+    ' and ensure OpenSSL 3 is available; on Linux/macOS install the shared library named in the error above.';
+/**
+ * Pull the extension file path out of lbug's load error. lbug's wrapper is
+ * English regardless of OS language — `Failed to load library: {path} which is
+ * needed by extension: {name}` (real lbug), or the quoted `Failed to load
+ * library '{path}': {reason}` variant — so the path is recoverable in any locale.
+ * Only paths ending in `.lbug_extension` are accepted, so a regex misfire can
+ * never point the inspector at an arbitrary file.
+ */
+export function extractExtensionPath(reason) {
+    const text = reason ?? '';
+    const m = /failed to load library:?\s*['"]?(.+?\.lbug_extension)/i.exec(text);
+    const path = m?.[1]?.trim();
+    return path && path.length > 0 ? path : null;
+}
+/** Node `process.arch` → PE `Machine`. Undefined for arches we don't map. */
+const PE_MACHINE = { x64: 0x8664, arm64: 0xaa64 };
+/** Node `process.arch` → ELF `e_machine`. */
+const ELF_MACHINE = { x64: 0x3e, arm64: 0xb7 };
+/** Node `process.arch` → Mach-O `cputype`. */
+const MACHO_CPUTYPE = { x64: 0x01000007, arm64: 0x0100000c };
+function classifyPE(buf, bytesRead, arch) {
+    if (bytesRead < 0x40 || buf[0] !== 0x4d || buf[1] !== 0x5a)
+        return 'corrupt'; // 'MZ'
+    const peOffset = buf.readUInt32LE(0x3c);
+    // The PE header (e_lfanew) points beyond what we read. A large-DOS-stub VALID PE
+    // and a garbage e_lfanew are indistinguishable from here, so don't claim 'corrupt'
+    // — defer to the loader's own report (#2383 F1-secondary).
+    if (peOffset + 6 > bytesRead)
+        return 'indeterminate';
+    const isPE = buf[peOffset] === 0x50 &&
+        buf[peOffset + 1] === 0x45 &&
+        buf[peOffset + 2] === 0 &&
+        buf[peOffset + 3] === 0;
+    if (!isPE)
+        return 'corrupt';
+    const expected = PE_MACHINE[arch];
+    if (expected === undefined)
+        return 'valid'; // arch we don't map: don't claim corrupt
+    return buf.readUInt16LE(peOffset + 4) === expected ? 'valid' : 'corrupt';
+}
+function classifyELF(buf, bytesRead, arch) {
+    if (bytesRead < 20)
+        return 'corrupt';
+    if (buf[0] !== 0x7f || buf[1] !== 0x45 || buf[2] !== 0x4c || buf[3] !== 0x46)
+        return 'corrupt'; // 0x7F ELF
+    const littleEndian = buf[5] === 1; // EI_DATA
+    const eMachine = littleEndian ? buf.readUInt16LE(18) : buf.readUInt16BE(18);
+    const expected = ELF_MACHINE[arch];
+    if (expected === undefined)
+        return 'valid';
+    return eMachine === expected ? 'valid' : 'corrupt';
+}
+function classifyMachO(buf, bytesRead, arch) {
+    if (bytesRead < 8)
+        return 'corrupt';
+    const magicLE = buf.readUInt32LE(0);
+    const magicBE = buf.readUInt32BE(0);
+    // Universal ("fat") binary — assume it carries the host slice.
+    if (magicBE === 0xcafebabe || magicLE === 0xcafebabe)
+        return 'valid';
+    const thin = magicLE === 0xfeedfacf || magicLE === 0xfeedface;
+    const thinSwapped = magicBE === 0xfeedfacf || magicBE === 0xfeedface;
+    if (!thin && !thinSwapped)
+        return 'corrupt';
+    const cpuType = thin ? buf.readUInt32LE(4) : buf.readUInt32BE(4);
+    const expected = MACHO_CPUTYPE[arch];
+    if (expected === undefined)
+        return 'valid';
+    return cpuType === expected ? 'valid' : 'corrupt';
+}
+/**
+ * Decide whether a binary header is a well-formed shared library for the given
+ * platform + architecture — using only the file's structure, no localized text.
+ * Pure and injectable (platform/arch as params) so every format+arch combination
+ * is unit-testable regardless of the host it runs on.
+ */
+export function classifyBinaryHeader(buf, bytesRead, platform, arch) {
+    if (platform === 'win32')
+        return classifyPE(buf, bytesRead, arch);
+    if (platform === 'linux')
+        return classifyELF(buf, bytesRead, arch);
+    if (platform === 'darwin')
+        return classifyMachO(buf, bytesRead, arch);
+    return 'valid'; // unknown host: never claim corrupt
+}
+const BINARY_HEADER_BYTES = 4096;
+/**
+ * Best-effort language-independent inspection of the extension file. Reads the
+ * header and classifies it; never throws — a missing file is `absent`, an
+ * unreadable one is `indeterminate`.
+ */
+export function inspectExtensionBinary(extensionPath) {
+    if (!extensionPath)
+        return 'indeterminate';
+    let fd;
+    try {
+        fd = openSync(extensionPath, 'r');
+    }
+    catch (err) {
+        return err?.code === 'ENOENT' ? 'absent' : 'indeterminate';
+    }
+    try {
+        const buf = Buffer.alloc(BINARY_HEADER_BYTES);
+        const bytesRead = readSync(fd, buf, 0, BINARY_HEADER_BYTES, 0);
+        return classifyBinaryHeader(buf, bytesRead, process.platform, process.arch);
+    }
+    catch {
+        return 'indeterminate';
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* closing the probe fd must never surface */
+        }
+    }
+}
+/**
+ * Diagnose a LadybugDB load failure, preferring a LANGUAGE-INDEPENDENT structural
+ * check of the extension binary over the localized error text:
+ *   - file absent             → missing_file
+ *   - present but malformed    → corrupt_file       (bad magic / wrong architecture)
+ *   - present and well-formed   → missing_dependency (a valid binary the loader rejected)
+ * The path comes from lbug's own English wrapper, so this holds in any OS display
+ * language. When the file cannot be located or read, it falls back to the string
+ * classifier (which still carries the language-independent hedged fallback). This
+ * is the entry point every surface should call.
+ */
+export function diagnoseExtensionLoad(reason) {
+    const text = reason ?? '';
+    const stringResult = classifyExtensionLoadError(text);
+    const fileState = inspectExtensionBinary(extractExtensionPath(text));
+    if (fileState === 'corrupt') {
+        return { kind: 'corrupt_file', remedy: CORRUPT_FILE_REMEDY };
+    }
+    if (fileState === 'valid') {
+        // The structural probe only inspects the first BINARY_HEADER_BYTES, so a file
+        // truncated AFTER its header still reads 'valid'. When the loader itself reported
+        // corruption (e.g. "file too short" / Windows error 193 "not a valid Win32
+        // application"), that whole-file verdict is stronger evidence than an intact-looking
+        // header — honor it and route to re-download, not a runtime-dependency install (#2383
+        // F1). Localized corrupt tails classify as hedged missing_dependency (not
+        // corrupt_file), so they still fall through to the dependency remedy below.
+        if (stringResult.kind === 'corrupt_file') {
+            return stringResult;
+        }
+        // A structurally sound binary that still failed to load ⇒ a dependency/runtime
+        // problem, decided WITHOUT the localized tail. Keep the string classifier's
+        // sharper remedy when it recognized the specific case (e.g. English 126).
+        const remedy = stringResult.kind === 'missing_dependency'
+            ? stringResult.remedy
+            : STRUCTURAL_MISSING_DEPENDENCY_REMEDY;
+        return { kind: 'missing_dependency', remedy };
+    }
+    // 'absent' or 'indeterminate' → no positive structural evidence, so defer to the
+    // string classifier. Note a real never-installed extension has NO path in its
+    // reason (lbug says "has not been installed"), so it lands here via
+    // 'indeterminate' and the string classifier reports missing_file correctly; a
+    // path that lbug named but that is now gone (stale/racy) is better judged by
+    // what lbug actually reported than by re-deriving from disk.
+    return stringResult;
+}