cgraphx 2.0.1 → 2.0.3

package/dist/core/code/engine/core/lbug/cypher-escape.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeCypherString = void 0;
+/**
+ * Escape a value for embedding in a single-quoted Cypher string literal.
+ *
+ * LadybugDB's parser uses backslash escapes and REJECTS SQL-style `''`
+ * doubling — `'we''ird'` is a parser error, not an escaped quote (#2409
+ * review). Every call site that used doubling produced a query that never
+ * parsed; the failures were invisible wherever the site swallowed errors
+ * (per-file deletes skipping quoted paths, importer BFS returning [],
+ * augment/wiki batch lookups silently missing rows).
+ *
+ * Backslashes are escaped first, then quotes — reversing the order would
+ * double the backslash that the quote escape just introduced. For values
+ * inside single-quoted literals only; table/label names go through
+ * `escapeTableName` in lbug-adapter instead.
+ *
+ * NOT for CSV emission: the COPY path (csv-generator.ts) quotes fields for
+ * LadybugDB's CSV reader (`ESCAPE='"'`), a different grammar with its own
+ * rules — its `''` usages are not this bug.
+ */
+const escapeCypherString = (value) => value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+exports.escapeCypherString = escapeCypherString;

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

@@ -0,0 +1,339 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_CORRUPTION_SIGNATURES = void 0;
+exports.classifyExtensionLoadError = classifyExtensionLoadError;
+exports.extractExtensionPath = extractExtensionPath;
+exports.classifyBinaryHeader = classifyBinaryHeader;
+exports.inspectExtensionBinary = inspectExtensionBinary;
+exports.diagnoseExtensionLoad = diagnoseExtensionLoad;
+/**
+ * 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 (the analyze degrade warning, capability diagnostics) 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.
+ */
+const node_fs_1 = require("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.
+exports.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 hedgedLoadFailureRemedy.
+ */
+const LOAD_FAILURE_WRAPPER = /failed to load library/i;
+// Remedies are label-parameterized (#2623 follow-up) so each extension's
+// failure is reported under its own name.
+const missingFileRemedy = (label) => `The ${label} extension is not installed. Re-run with network access and ` +
+    `CGRAPH_LBUG_EXTENSION_INSTALL=auto to download it.`;
+const corruptFileRemedy = (label) => `The ${label} extension file is present but unreadable (corrupt, truncated, or built for another ` +
+    `platform). Re-download it with network access and ` +
+    `CGRAPH_LBUG_EXTENSION_INSTALL=auto.`;
+// 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';
+// Git for Windows already ships the OpenSSL 3 DLLs in its mingw64 bin directory,
+// so the identical command that fails in PowerShell succeeds in Git Bash (#2669
+// reporter, who had the VC++ redist installed and still failed until that
+// directory was on PATH). Deliberately a fixed system path and never a
+// user-profile one, so no `C:\Users\…` path ever reaches a user through this
+// surface.
+const GIT_BASH_OPENSSL_HINT = ' If Git for Windows is installed you already have those DLLs: run the same command from Git Bash, ' +
+    'or prepend "C:\\Program Files\\Git\\mingw64\\bin" to PATH.';
+// MSVC-first per DuckDB's canonical answer for this exact error; OpenSSL second.
+const windowsMissingDependencyRemedy = (label) => `The ${label} 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.' +
+    GIT_BASH_OPENSSL_HINT;
+const posixMissingDependencyRemedy = (label) => `The ${label} 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 hedgedLoadFailureRemedy = (label) => `The ${label} 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, ' +
+    're-run analyze with network access and CGRAPH_LBUG_EXTENSION_INSTALL=auto to re-download.';
+const unknownRemedy = (label) => `The ${label} extension failed to load for an unrecognized reason. Verify the extension ` +
+    `file and platform; re-install with network access and CGRAPH_LBUG_EXTENSION_INSTALL=auto.`;
+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.
+ */
+function classifyExtensionLoadError(reason, label = 'optional') {
+    const text = reason ?? '';
+    if (matchesAny(text, MISSING_FILE_SIGNATURES)) {
+        return { kind: 'missing_file', remedy: missingFileRemedy(label) };
+    }
+    if (matchesAny(text, exports.FILE_CORRUPTION_SIGNATURES)) {
+        return { kind: 'corrupt_file', remedy: corruptFileRemedy(label) };
+    }
+    if (matchesAny(text, WINDOWS_MISSING_DEPENDENCY_SIGNATURES)) {
+        return { kind: 'missing_dependency', remedy: windowsMissingDependencyRemedy(label) };
+    }
+    if (matchesAny(text, POSIX_MISSING_DEPENDENCY_SIGNATURES)) {
+        return { kind: 'missing_dependency', remedy: posixMissingDependencyRemedy(label) };
+    }
+    // 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: hedgedLoadFailureRemedy(label) };
+    }
+    return { kind: 'unknown', remedy: unknownRemedy(label) };
+}
+const structuralMissingDependencyRemedy = (label) => `The ${label} 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.' +
+    GIT_BASH_OPENSSL_HINT;
+/**
+ * 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.
+ */
+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.
+ */
+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`.
+ */
+function inspectExtensionBinary(extensionPath) {
+    if (!extensionPath)
+        return 'indeterminate';
+    let fd;
+    try {
+        fd = (0, node_fs_1.openSync)(extensionPath, 'r');
+    }
+    catch (err) {
+        return err?.code === 'ENOENT' ? 'absent' : 'indeterminate';
+    }
+    try {
+        const buf = Buffer.alloc(BINARY_HEADER_BYTES);
+        const bytesRead = (0, node_fs_1.readSync)(fd, buf, 0, BINARY_HEADER_BYTES, 0);
+        return classifyBinaryHeader(buf, bytesRead, process.platform, process.arch);
+    }
+    catch {
+        return 'indeterminate';
+    }
+    finally {
+        try {
+            (0, node_fs_1.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.
+ */
+function diagnoseExtensionLoad(reason, label = 'optional') {
+    const text = reason ?? '';
+    const stringResult = classifyExtensionLoadError(text, label);
+    const fileState = inspectExtensionBinary(extractExtensionPath(text));
+    if (fileState === 'corrupt') {
+        return { kind: 'corrupt_file', remedy: corruptFileRemedy(label) };
+    }
+    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
+            : structuralMissingDependencyRemedy(label);
+        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;
+}

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

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetExtensionState = exports.getExtensionCapability = exports.getExtensionCapabilities = exports.extensionManager = exports.ExtensionManager = exports.installDuckDbExtensionOutOfProcess = exports.getExtensionInstallChildProcessArgs = exports.getExtensionInstallTimeoutMs = exports.resolveAnalyzeInstallPolicy = exports.getExtensionInstallPolicy = void 0;
+const child_process_1 = require("child_process");
+const node_url_1 = require("node:url");
+const lbug_config_js_1 = require("./lbug-config.js");
+const extension_load_error_js_1 = require("./extension-load-error.js");
+const logger_js_1 = require("../logger.js");
+const DEFAULT_EXTENSION_INSTALL_TIMEOUT_MS = 15_000;
+const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+const alreadyAvailable = (message) => message.includes('already loaded') ||
+    message.includes('already installed') ||
+    message.includes('already exists');
+/** LadybugDB errors are multi-line; collapse for single-line warn/reason strings. */
+const oneLine = (value) => value.replace(/\s+/g, ' ').trim();
+const resolvePolicyFromEnv = () => {
+    const raw = process.env.CGRAPH_LBUG_EXTENSION_INSTALL;
+    if (raw === 'load-only' || raw === 'never' || raw === 'auto')
+        return raw;
+    return 'load-only';
+};
+const getExtensionInstallPolicy = () => resolvePolicyFromEnv();
+exports.getExtensionInstallPolicy = getExtensionInstallPolicy;
+/**
+ * Install policy for the **analyze (write) path**.
+ *
+ * The global default (`resolvePolicyFromEnv`) is `load-only` so read paths
+ * never require outbound network access (PR #1161, offline-first). The analyze
+ * path is different: it owns building optional-extension-backed indexes, so it
+ * defaults to `auto` — LOAD the extension if present, otherwise attempt one
+ * bounded out-of-process INSTALL (the VECTOR/embeddings path, #726 contract).
+ * An explicit `CGRAPH_LBUG_EXTENSION_INSTALL` value still wins, so operators
+ * can force `load-only`/`never` for fully offline analyze; `auto` LOADs-first,
+ * so offline machines still degrade gracefully when the INSTALL cannot reach
+ * the network.
+ */
+const resolveAnalyzeInstallPolicy = () => {
+    const raw = process.env.CGRAPH_LBUG_EXTENSION_INSTALL;
+    if (raw === 'load-only' || raw === 'never' || raw === 'auto')
+        return raw;
+    return 'auto';
+};
+exports.resolveAnalyzeInstallPolicy = resolveAnalyzeInstallPolicy;
+const getExtensionInstallTimeoutMs = () => {
+    const raw = process.env.CGRAPH_LBUG_EXTENSION_INSTALL_TIMEOUT_MS;
+    const parsed = raw ? Number(raw) : NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_EXTENSION_INSTALL_TIMEOUT_MS;
+};
+exports.getExtensionInstallTimeoutMs = getExtensionInstallTimeoutMs;
+const getExtensionInstallChildProcessArgs = (extensionName, maxDbSize = lbug_config_js_1.LBUG_MAX_DB_SIZE) => {
+    const childScript = new URL('../../../scripts/install-duckdb-extension.mjs', (0, node_url_1.pathToFileURL)(__filename));
+    return [(0, node_url_1.fileURLToPath)(childScript), extensionName, String(maxDbSize)];
+};
+exports.getExtensionInstallChildProcessArgs = getExtensionInstallChildProcessArgs;
+/**
+ * Run `INSTALL <extension>` in a short-lived child Node process so the parent
+ * event loop is never blocked by DuckDB's synchronous network call.
+ *
+ * The child opens its own scratch LadybugDB, executes the install, and exits.
+ * If the child exceeds `timeoutMs` the parent kills it with SIGKILL and
+ * resolves with `timedOut: true`.
+ */
+const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutMs = (0, exports.getExtensionInstallTimeoutMs)(), loadError) => {
+    if (!EXTENSION_NAME_PATTERN.test(extensionName)) {
+        throw new Error(`Invalid DuckDB extension name: ${extensionName}`);
+    }
+    return await new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)(process.execPath, (0, exports.getExtensionInstallChildProcessArgs)(extensionName), {
+            env: {
+                ...process.env,
+                CGRAPH_LBUG_EXTENSION_NAME: extensionName,
+                // The child picks INSTALL vs FORCE INSTALL from this LOAD error so it
+                // only re-downloads when the on-disk extension file is actually broken.
+                ...(loadError ? { CGRAPH_LBUG_EXTENSION_LOAD_ERROR: loadError } : {}),
+            },
+            stdio: ['ignore', 'ignore', 'pipe'],
+            windowsHide: true,
+        });
+        let stderr = '';
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk) => {
+            stderr = (stderr + chunk).slice(-4000);
+        });
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill('SIGKILL');
+            resolve({
+                success: false,
+                timedOut: true,
+                message: `extension install for ${extensionName} timed out after ${timeoutMs}ms`,
+            });
+        }, timeoutMs);
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ success: false, timedOut: false, message: err.message });
+        });
+        child.on('exit', (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                success: code === 0,
+                timedOut: false,
+                message: code === 0
+                    ? `extension install for ${extensionName} completed`
+                    : `extension install for ${extensionName} failed with ${signal ?? `exit code ${code}`}${stderr ? `: ${stderr.trim()}` : ''}`,
+            });
+        });
+    });
+};
+exports.installDuckDbExtensionOutOfProcess = installDuckDbExtensionOutOfProcess;
+/**
+ * Centralized lifecycle manager for optional LadybugDB extensions.
+ *
+ * Always tries `LOAD EXTENSION <name>` first — it is per-connection,
+ * idempotent, and never touches the network. If `LOAD` fails and the active
+ * policy permits, the manager runs a single bounded out-of-process `INSTALL`
+ * attempt per process and retries `LOAD`. Capability outcomes are cached so
+ * unavailable extensions degrade search features without ever blocking
+ * subsequent analyze or query calls.
+ *
+ * Policy precedence (most specific wins):
+ *   per-call `opts.policy` → constructor `options.policy` → env → `load-only`
+ */
+class ExtensionManager {
+    options;
+    capabilities = new Map();
+    installAttempted = new Map();
+    warnedKeys = new Set();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Reset cached capability and install state. Test-only. */
+    reset() {
+        this.capabilities.clear();
+        this.installAttempted.clear();
+        this.warnedKeys.clear();
+    }
+    /** Snapshot of currently-known optional extension capabilities. */
+    getCapabilities() {
+        return Array.from(this.capabilities.values());
+    }
+    /**
+     * Ensure an optional extension is loaded on the supplied connection.
+     *
+     * Returns `true` when the extension is usable on `query`, `false` when it
+     * is unavailable. Never throws on install failure — analyze and query
+     * paths are expected to degrade gracefully.
+     */
+    async ensure(query, name, label, opts = {}) {
+        if (!EXTENSION_NAME_PATTERN.test(name)) {
+            throw new Error(`Invalid DuckDB extension name: ${name}`);
+        }
+        const policy = opts.policy ?? this.options.policy ?? resolvePolicyFromEnv();
+        const timeoutMs = opts.installTimeoutMs ?? this.options.installTimeoutMs ?? (0, exports.getExtensionInstallTimeoutMs)();
+        const warn = this.options.warn ?? ((msg) => logger_js_1.logger.warn(msg));
+        const quiet = opts.quiet === true;
+        if (policy === 'never') {
+            this.markUnavailable(name, label, 'extension install policy is "never"', warn, quiet);
+            return false;
+        }
+        const loadError = await this.tryLoad(query, name);
+        if (loadError === null) {
+            this.markLoaded(name);
+            return true;
+        }
+        if (policy === 'load-only') {
+            this.markUnavailable(name, label, `load-only policy (no install attempted); LOAD ${name} failed: ${loadError}`, warn, quiet);
+            return false;
+        }
+        let install = this.installAttempted.get(name);
+        if (!install) {
+            const installFn = this.options.installExtension ?? exports.installDuckDbExtensionOutOfProcess;
+            // Hand the child the LOAD error so it re-downloads (FORCE) only when the
+            // present extension file is provably broken, not on every LOAD failure.
+            install = await installFn(name, timeoutMs, loadError);
+            this.installAttempted.set(name, install);
+        }
+        if (!install.success) {
+            this.markUnavailable(name, label, `${install.message}; LOAD ${name} had failed: ${loadError}`, warn, quiet);
+            return false;
+        }
+        const retryError = await this.tryLoad(query, name);
+        if (retryError === null) {
+            this.markLoaded(name);
+            return true;
+        }
+        this.markUnavailable(name, label, `LOAD ${name} failed after successful INSTALL: ${retryError}`, warn, quiet);
+        return false;
+    }
+    /**
+     * Attempt `LOAD EXTENSION <name>`; returns `null` on success and the
+     * collapsed error message on failure. The message is the load-side ground
+     * truth — LadybugDB distinguishes a missing extension file from a present
+     * but unloadable one (wrong platform, truncated download, version mismatch),
+     * and discarding it left users staring at "not pre-installed" when the file
+     * existed all along (#2374).
+     */
+    async tryLoad(query, name) {
+        try {
+            await query(`LOAD EXTENSION ${name}`);
+            return null;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return alreadyAvailable(msg) ? null : oneLine(msg);
+        }
+    }
+    markLoaded(name) {
+        this.capabilities.set(name, { name, loaded: true });
+    }
+    markUnavailable(name, label, reason, warn, quiet = false) {
+        // Classify once here (the single load-failure sink, run per Database not per
+        // request) so the hot per-request warning path does no file I/O (#2383 F3).
+        this.capabilities.set(name, {
+            name,
+            loaded: false,
+            reason,
+            diagnosis: (0, extension_load_error_js_1.diagnoseExtensionLoad)(reason, label),
+        });
+        const message = `GitNexus: ${label} extension unavailable; continuing without ${label} features. ${reason}`;
+        // A quiet probe must not register the dedup key: the owning caller may hit
+        // the identical reason later, and that one is the real degradation report.
+        if (quiet) {
+            logger_js_1.logger.debug(message);
+            return;
+        }
+        const key = `${name}:${reason}`;
+        if (this.warnedKeys.has(key))
+            return;
+        this.warnedKeys.add(key);
+        warn(message);
+    }
+}
+exports.ExtensionManager = ExtensionManager;
+/** Process-wide singleton shared by core and pool adapters. */
+exports.extensionManager = new ExtensionManager();
+/** Snapshot of which optional DuckDB extensions are loaded in this process. */
+const getExtensionCapabilities = () => exports.extensionManager.getCapabilities();
+exports.getExtensionCapabilities = getExtensionCapabilities;
+/**
+ * One optional extension's capability record, or `undefined` when nothing in
+ * this process has resolved it yet.
+ *
+ * `getExtensionCapabilities().find((c) => c.name === …)` was spelled out at five
+ * call sites across four modules (#2841 review), each re-deriving the same
+ * lookup — and each free to drift on the extension NAME, which is the one string
+ * the lookup is keyed on. Keep the name in one place.
+ */
+const getExtensionCapability = (name) => (0, exports.getExtensionCapabilities)().find((c) => c.name === name);
+exports.getExtensionCapability = getExtensionCapability;
+/** Test-only: clear the singleton's cached capability and install state. */
+const resetExtensionState = () => exports.extensionManager.reset();
+exports.resetExtensionState = resetExtensionState;