gitnexus 1.6.10-rc.89 → 1.6.10-rc.90

package/README.md

@@ -484,7 +484,7 @@ Configure the behavior with these environment variables:
 | `GITNEXUS_FTS_CJK_SEGMENTATION`              | `none`, `bigram`               | `none`              | `bigram` inserts overlapping character-bigram boundaries into Chinese/Japanese Han-ideograph spans in `content`/`description` before FTS indexing, so LadybugDB's space-only tokenizer can see sub-phrase word boundaries. Scoped to CJK Unified Ideographs only — Japanese Hiragana/Katakana and Korean Hangul are not currently segmented. Unlike `GITNEXUS_FTS_STEMMER`, this rewrites stored text — enabling it on an already-indexed repo requires a full `gitnexus analyze --force`; neither `--repair-fts` nor a plain incremental `analyze` applies it to previously-indexed files. Set the same value wherever `analyze` and search-serving processes (CLI query, MCP server, web server) run. |
 | `GITNEXUS_COMMUNITY_ENGINE`                  | `graphology`, `icebug`, `auto` | `graphology`        | Community-detection engine used during analyze. `graphology` uses the bundled default path. `icebug` and `auto` currently behave identically: both try the experimental Icebug CSR path and fall back to Graphology if the optional native module is unavailable or incompatible.                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`                | `67108864` (64 MiB) | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments.                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `GITNEXUS_LBUG_BUFFER_POOL_SIZE`             | integer `>= 0` (bytes)         | min(2 GiB, 80% RAM) | LadybugDB buffer-pool ceiling for every GitNexus database (analyze, MCP server, serve, group bridges). Bounded so a long-lived `gitnexus mcp` process or a large incremental `analyze` cannot grow toward LadybugDB's native 80%-of-RAM default and OOM the host (#2557). `0` restores that native unbounded default; invalid values warn and fall back to the default.                                                                                                                                                                                                                                                                                                                                  |
+| `GITNEXUS_LBUG_BUFFER_POOL_SIZE`             | integer `>= 0` (bytes)         | min(2 GiB, 80% RAM) | LadybugDB buffer-pool ceiling for every GitNexus database (analyze, MCP server, serve, group bridges). Bounded so a long-lived `gitnexus mcp` process or a large incremental `analyze` cannot grow toward LadybugDB's native 80%-of-RAM default and OOM the host (#2557). `0` restores that native unbounded default; invalid values warn and fall back to the default. During `analyze` the pool is right-sized to the graph and, on non-4 KiB-page hosts (Apple Silicon 16 KiB, Ascend/aarch64 64 KiB), scaled by the page-size granule ratio up to min(2 GiB × pageSize/4 KiB, 80% RAM) (#2631); this env var overrides all of that as an absolute value.                                                                                                                                                                                                                                                                                                                                  |
 | `GITNEXUS_LBUG_MAX_DB_SIZE`                  | positive integer (bytes)       | `17179869184` (16 GiB) | Upper bound for a single LadybugDB database file. This is an mmap/disk-address-space ceiling, not a memory limit — it does not constrain the buffer pool (use `GITNEXUS_LBUG_BUFFER_POOL_SIZE` for that). Raise it when indexing genuinely huge monorepos; invalid values silently fall back to the default.                                                                                                                                                                                                                                                                                                                                                                                             |
 
 ```bash

package/dist/cli/doctor.d.ts

@@ -36,4 +36,15 @@ export declare function localEmbeddingDoctorStatus(opts: {
  * detect the OS page size at runtime).
  */
 export declare function pageSizeDoctorLines(pageSize: number | undefined, ladybugVersion: string | undefined): string[];
+/**
+ * The hintless buffer-pool doctor line (#2631) — the pool the next Database
+ * open in THIS process would get. Same plain-params testable-helper shape as
+ * pageSizeDoctorLines above. `pool` is getEffectiveBufferPoolSize(): `0` is
+ * the pass-through sentinel for LadybugDB's native 80%-of-RAM default, never
+ * printed as "0 MiB". `envRaw` (the raw GITNEXUS_LBUG_BUFFER_POOL_SIZE value)
+ * marks operator-supplied absolute values as "(env override)" — no scaling
+ * suffix: the hintless default is deliberately unscaled (#2557), and an env
+ * value is absolute, so a "×N" note would misdescribe both.
+ */
+export declare function poolSizeDoctorLine(pool: number, envRaw: string | undefined): string;
 export declare const doctorCommand: () => Promise<void>;

package/dist/cli/doctor.js

@@ -5,7 +5,7 @@ import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage,
 import { isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
 import { checkLbugNative, probeFtsExtensionLoad, probeVectorExtensionLoad, } from '../core/lbug/native-check.js';
-import { getOsPageSize, isPageSizeAwareLadybug } from '../core/lbug/lbug-config.js';
+import { getEffectiveBufferPoolSize, getOsPageSize, isPageSizeAwareLadybug, } from '../core/lbug/lbug-config.js';
 import { diagnoseExtensionLoad } from '../core/lbug/extension-load-error.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
@@ -115,6 +115,21 @@ export function pageSizeDoctorLines(pageSize, ladybugVersion) {
     }
     return lines;
 }
+/**
+ * The hintless buffer-pool doctor line (#2631) — the pool the next Database
+ * open in THIS process would get. Same plain-params testable-helper shape as
+ * pageSizeDoctorLines above. `pool` is getEffectiveBufferPoolSize(): `0` is
+ * the pass-through sentinel for LadybugDB's native 80%-of-RAM default, never
+ * printed as "0 MiB". `envRaw` (the raw GITNEXUS_LBUG_BUFFER_POOL_SIZE value)
+ * marks operator-supplied absolute values as "(env override)" — no scaling
+ * suffix: the hintless default is deliberately unscaled (#2557), and an env
+ * value is absolute, so a "×N" note would misdescribe both.
+ */
+export function poolSizeDoctorLine(pool, envRaw) {
+    const value = pool === 0 ? 'native 80% of RAM' : `${Math.round(pool / (1024 * 1024))} MiB`;
+    const envNote = envRaw !== undefined && envRaw.trim().length > 0 ? ' (env override)' : '';
+    return `  ${padDisplayEnd('pool size', 10)}${value}${envNote}`;
+}
 export const doctorCommand = async () => {
     const fingerprint = getRuntimeFingerprint();
     const capabilities = getRuntimeCapabilities();
@@ -132,6 +147,9 @@ export const doctorCommand = async () => {
     for (const line of pageSizeDoctorLines(getOsPageSize(), fingerprint.ladybugdb)) {
         console.log(line);
     }
+    // Hintless buffer pool for the next DB open (#2631). Literal label like
+    // the page size line above (no i18n key).
+    console.log(poolSizeDoctorLine(getEffectiveBufferPoolSize(), process.env.GITNEXUS_LBUG_BUFFER_POOL_SIZE));
     const nativeCheck = checkLbugNative();
     if (nativeCheck.ok) {
         console.log(`  ${padDisplayEnd('native', 10)}✓ lbugjs.node loaded`);

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

@@ -14,7 +14,7 @@ import { streamAllCSVsToDisk } from './csv-generator.js';
 import { getNodeLabel as deriveNodeLabel } from './rel-pair-routing.js';
 import { EMBEDDABLE_LABELS } from '../embeddings/types.js';
 import { extensionManager, resolveAnalyzeInstallPolicy, } from './extension-loader.js';
-import { classifyDeleteAllError, closeLbugConnection, HANDLE_RELEASE_PROBE_ATTEMPTS, HANDLE_RELEASE_PROBE_DELAY_MS, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, openLbugConnection, sleep, toNativeSafePath, resolveNativeSafeStorageDir, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
+import { classifyDeleteAllError, closeLbugConnection, HANDLE_RELEASE_PROBE_ATTEMPTS, HANDLE_RELEASE_PROBE_DELAY_MS, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, bufferPoolExhaustionRemedy, openLbugConnection, sleep, toNativeSafePath, resolveNativeSafeStorageDir, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
 import { finalizeLbugSidecarsAfterClose, guardWalQuarantine, isMissingShadowSidecarError, isReadOnlyShadowReplayError, lbugLockRemediation, preflightLbugSidecars, quarantineWalForMissingShadow, renameFailureMessage, shadowSidecarRecoveryMessage, } from './sidecar-recovery.js';
 import { logger } from '../logger.js';
 /**
@@ -796,7 +796,12 @@ const copyNodeCSVs = async (targetConn, nodeFileEntries, log, totalSteps) => {
         const copyQuery = getCopyQuery(table, normalizeCopyPath(csvPath));
         await copyCsvWithRetry(targetConn, copyQuery, (retryErr) => {
             const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
-            throw new Error(`COPY failed for ${table}: ${retryMsg.slice(0, 200)}`);
+            // Pool exhaustion gets a remedy (#2631): the raw binder text gives the
+            // operator nothing to act on, and on non-4K-page hosts (Ascend aarch64,
+            // Apple Silicon) the pool bills up to pageSize/4KiB x faster than the
+            // sizing was calibrated for — name the knob and the mechanism.
+            const remedy = bufferPoolExhaustionRemedy(retryMsg);
+            throw new Error(`COPY failed for ${table}: ${retryMsg.slice(0, 200)}${remedy ? ` ${remedy}` : ''}`);
         });
     }
 };
@@ -944,6 +949,7 @@ pdgEmitManifest) => {
     let tFallback = tCopyNodes;
     const insertedRels = totalValidRels;
     const warnings = [];
+    let poolRemedyIssued = false;
     if (insertedRels > 0) {
         log(`Loading edges: ${insertedRels.toLocaleString()} across ${relsByPair.size} types`);
         let pairIdx = 0;
@@ -966,6 +972,17 @@ pdgEmitManifest) => {
             await copyCsvWithRetry(writeConn, copyQuery, (retryErr) => {
                 const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
                 warnings.push(`${fromLabel}->${toLabel} (${rows} edges): ${retryMsg.slice(0, 80)}`);
+                // One remedy per bulk load, not per pair (#2631): pool exhaustion
+                // repeats for every remaining pair once it starts. logger.warn, not
+                // just warnings.push — the returned warnings array has no consumer at
+                // any call site, so a push alone would leave the remedy invisible
+                // while the row-by-row fallback quietly degrades the load.
+                const remedy = poolRemedyIssued ? undefined : bufferPoolExhaustionRemedy(retryMsg);
+                if (remedy) {
+                    poolRemedyIssued = true;
+                    warnings.push(remedy);
+                    logger.warn(remedy);
+                }
                 failedPairEdges += rows;
                 failedPairCsvPaths.add(pairCsvPath);
             });

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

@@ -61,16 +61,68 @@ export declare function resolveNativeSafeStorageDir(storagePath: string, subdir:
  */
 export declare const LBUG_MAX_DB_SIZE: number;
 export declare const parseWalCheckpointThreshold: (raw: string | undefined) => number | undefined;
+/**
+ * How much the OS page size amplifies buffer-pool consumption (#2631).
+ *
+ * LadybugDB's VM region charges pool budget per DISCARD GRANULE, not per
+ * frame: `discardGranuleSize = max(frameSize, osPageSize)` (vm_region.cpp),
+ * `claimFrame` bills the whole granule when its first 4 KiB frame becomes
+ * resident, and `releaseFrame` refunds only when the granule's LAST frame
+ * leaves. On a 64 KiB-page kernel (aarch64 openEuler — Ascend hosts) that is
+ * 16 frames per granule: scattered access is billed up to 16× its real bytes,
+ * and whole eviction passes can evict frames yet refund nothing — which is
+ * exactly the engine's "buffer pool is full and no memory could be freed"
+ * throw. Apple Silicon macOS (16 KiB pages) is the same mechanism at 4×.
+ *
+ * So the ANALYZE-path pool sizes (the per-element estimate, the COPY-safety
+ * floor, and the cap the hint is clamped against) are scaled by this ratio:
+ * the budget must cover worst-case granule charging or COPY dies on non-4K
+ * hosts with a pool that would be ample on x86. The hintless default
+ * (defaultBufferPoolSize — MCP serve, doctor, native-check) is deliberately
+ * NOT scaled: the pool is a native eager allocation committed at DB open
+ * (measured — see POOL_BYTES_PER_ELEMENT below), so scaling the global
+ * default would revert the #2557 OOM cap on every 16 KiB/64 KiB host. If the
+ * engine ever charges per-frame (or ships page-size-matched frames), this
+ * collapses back to 1 and the scaling disappears.
+ *
+ * Fail-safe: an undetectable page size (win32 — where the granule mechanism
+ * is absent anyway — or a failed `getconf`) means ratio 1, i.e. today's
+ * behavior.
+ */
+export declare const granuleRatio: (pageSize?: number | undefined) => number;
 /**
  * Size the buffer pool to an estimated graph size (node + relationship count),
- * clamped to [ADAPTIVE_POOL_FLOOR, defaultBufferPoolSize()]. The estimate can
- * only *shrink* the pool from the default — never above the 2 GiB / 80%-RAM cap,
- * never below the COPY-safety floor — so no repo is under-sized or gets more
- * than the default it would have today.
+ * clamped to [ADAPTIVE_POOL_FLOOR, scaledAnalyzePoolCap], with every term
+ * scaled by granuleRatio (#2631): on non-4K hosts the engine bills pool
+ * budget per OS-page-sized granule, so the same graph consumes up to
+ * pageSize/4096 × the budget it needs on x86. On 4 KiB hosts the ratio is 1
+ * and this is byte-identical to the pre-#2631 behavior. The estimate is never
+ * above the page-size-scaled #2557 cap bounded by 80% of RAM, never below the
+ * scaled COPY-safety floor; the hintless default stays unscaled.
+ *
+ * `pageSize` is a test seam (the pageSizeDoctorLines convention); production
+ * callers omit it and get the memoized real OS page size.
  */
-export declare const estimateBufferPool: (graphElementCount: number) => number;
+export declare const estimateBufferPool: (graphElementCount: number, pageSize?: number | undefined) => number;
 /** Set (bytes) or clear (`undefined`) the per-run buffer-pool size hint. */
 export declare const setBufferPoolSizeHint: (bytes: number | undefined) => void;
+/**
+ * Doctor-facing view of the pool size the next Database open would get
+ * (#2631): env override > clamped hint > unscaled hintless default. Read-only;
+ * doctor prints it next to the page-size lines so support triage sees the
+ * sizing inputs at a glance. `0` is the pass-through sentinel for LadybugDB's
+ * native 80%-of-RAM default — callers must label it, not print "0 MiB".
+ */
+export declare const getEffectiveBufferPoolSize: () => number;
+/**
+ * Actionable remedy for a buffer-pool exhaustion error (#2631), or undefined
+ * when `message` is not that class. Cause → consequence → remedy, the
+ * diagnoseExtensionLoad convention: names the effective pool, the override
+ * knob, and — on non-4K hosts — the granule amplification that makes the
+ * budget exhaust early (the reporter's Ascend/aarch64 64 KiB kernel billed a
+ * pool up to 16× faster than the same analyze on x86).
+ */
+export declare const bufferPoolExhaustionRemedy: (message: string, pageSize?: number | undefined) => string | undefined;
 export declare const WAL_RECOVERY_SUGGESTION = "WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.";
 export declare function isWalCorruptionError(err: unknown): boolean;
 /**
@@ -83,8 +135,12 @@ export declare const isLbugCheckpointIoError: (err: unknown) => boolean;
  * True when `err` looks like the LadybugDB buffer manager failing to release
  * frame memory — the failure mode of a 4 KiB page-size assumption on a
  * 16 KiB/64 KiB-page kernel (#1231). Deliberately does NOT match the
- * generic "buffer pool is full" exhaustion error, which is a sizing
- * problem, not a page-size one.
+ * generic "buffer pool is full" exhaustion error: that one is handled as a
+ * SIZING problem — though since #2631 we know page size drives sizing too
+ * (the engine bills pool budget per OS-page-sized discard granule, so non-4K
+ * hosts exhaust the same budget up to pageSize/4096× earlier; see
+ * granuleRatio, which scales the pool accordingly, and
+ * bufferPoolExhaustionRemedy, which explains it to the operator).
  */
 export declare const isLbugPageSizeFrameError: (err: unknown) => boolean;
 /**
@@ -94,6 +150,13 @@ export declare const isLbugPageSizeFrameError: (err: unknown) => boolean;
  * side of showing the upgrade hint.
  */
 export declare const isPageSizeAwareLadybug: (version: string | undefined) => boolean;
+/**
+ * Test seam (the `_captureLogger` convention): pin the memoized OS page size
+ * so sizing tests are host-independent — without this they would silently
+ * drift on 16 KiB-page Apple Silicon runners. `number` pins a value, `null`
+ * pins "undetectable", `undefined` clears the memo so the next call re-probes.
+ */
+export declare const _setOsPageSizeForTests: (pageSize: number | null | undefined) => void;
 /**
  * OS memory page size in bytes, or `undefined` when it cannot be determined
  * (Windows, missing getconf, sandboxed exec). Node exposes no page-size API,
@@ -102,8 +165,6 @@ export declare const isPageSizeAwareLadybug: (version: string | undefined) => bo
  * an explicit killSignal (see the options comment below).
  */
 export declare const getOsPageSize: () => number | undefined;
-/** Exported only for unit tests — clears the getconf probe cache. */
-export declare const _resetOsPageSizeCacheForTest: () => void;
 type LbugModule = typeof lbug;
 export interface LbugDatabaseOptions {
     readOnly?: boolean;

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

@@ -327,15 +327,72 @@ const parseBufferPoolSize = (raw) => {
         return undefined;
     return Math.floor(parsed);
 };
+/**
+ * The buffer-manager frame size compiled into every shipped `@ladybugdb/core`
+ * binary (`LBUG_PAGE_SIZE_LOG2 = 12` in the engine's CMake) — frames are 4 KiB
+ * on every platform, independent of the OS page size.
+ */
+const LBUG_ASSUMED_FRAME_SIZE = 4096;
+/**
+ * How much the OS page size amplifies buffer-pool consumption (#2631).
+ *
+ * LadybugDB's VM region charges pool budget per DISCARD GRANULE, not per
+ * frame: `discardGranuleSize = max(frameSize, osPageSize)` (vm_region.cpp),
+ * `claimFrame` bills the whole granule when its first 4 KiB frame becomes
+ * resident, and `releaseFrame` refunds only when the granule's LAST frame
+ * leaves. On a 64 KiB-page kernel (aarch64 openEuler — Ascend hosts) that is
+ * 16 frames per granule: scattered access is billed up to 16× its real bytes,
+ * and whole eviction passes can evict frames yet refund nothing — which is
+ * exactly the engine's "buffer pool is full and no memory could be freed"
+ * throw. Apple Silicon macOS (16 KiB pages) is the same mechanism at 4×.
+ *
+ * So the ANALYZE-path pool sizes (the per-element estimate, the COPY-safety
+ * floor, and the cap the hint is clamped against) are scaled by this ratio:
+ * the budget must cover worst-case granule charging or COPY dies on non-4K
+ * hosts with a pool that would be ample on x86. The hintless default
+ * (defaultBufferPoolSize — MCP serve, doctor, native-check) is deliberately
+ * NOT scaled: the pool is a native eager allocation committed at DB open
+ * (measured — see POOL_BYTES_PER_ELEMENT below), so scaling the global
+ * default would revert the #2557 OOM cap on every 16 KiB/64 KiB host. If the
+ * engine ever charges per-frame (or ships page-size-matched frames), this
+ * collapses back to 1 and the scaling disappears.
+ *
+ * Fail-safe: an undetectable page size (win32 — where the granule mechanism
+ * is absent anyway — or a failed `getconf`) means ratio 1, i.e. today's
+ * behavior.
+ */
+export const granuleRatio = (pageSize = getOsPageSize()) => {
+    if (pageSize === undefined || !Number.isFinite(pageSize))
+        return 1;
+    return Math.max(1, Math.floor(pageSize / LBUG_ASSUMED_FRAME_SIZE));
+};
+/**
+ * Hintless pool default — MCP serve, doctor, native-check, any open without a
+ * per-run hint. Deliberately UNSCALED (#2557): the pool is an eager native
+ * allocation at DB open, so a page-size-scaled default would hand a
+ * long-lived `gitnexus mcp` on a 16 KiB/64 KiB host up to 80% of RAM — the
+ * exact OOM exposure the 2 GiB cap was added to remove.
+ */
 const defaultBufferPoolSize = () => Math.min(DEFAULT_BUFFER_POOL_CAP, Math.max(BUFFER_POOL_FLOOR, Math.floor(os.totalmem() * 0.8)));
 /**
- * Clamp an adaptive pool request to [ADAPTIVE_POOL_FLOOR, default]. The lower
- * bound keeps LadybugDB's COPY viable; the upper bound (defaultBufferPoolSize)
- * means the hint can only shrink the pool from today's default and can never
- * exceed the 2 GiB / 80%-RAM cap — and on a machine whose default is below the
- * COPY floor, the default wins, so the pool is never over-committed.
+ * Upper bound for the ANALYZE-path (hinted) pool: the #2557 cap scaled by the
+ * granule ratio, still bounded by 80% of RAM. Scaling only this bound — and
+ * not defaultBufferPoolSize — is what lets the #2631 fix take effect during
+ * the bulk COPY without touching hintless opens: with an unscaled cap the
+ * min() below would clamp the scaled COPY floor straight back to 2 GiB.
  */
-const clampBufferPool = (bytes) => Math.min(defaultBufferPoolSize(), Math.max(ADAPTIVE_POOL_FLOOR, Math.floor(bytes)));
+const scaledAnalyzePoolCap = (pageSize) => Math.min(DEFAULT_BUFFER_POOL_CAP * granuleRatio(pageSize), Math.max(BUFFER_POOL_FLOOR, Math.floor(os.totalmem() * 0.8)));
+/**
+ * Clamp an adaptive pool request to [ADAPTIVE_POOL_FLOOR × granuleRatio,
+ * scaledAnalyzePoolCap]. The lower bound keeps LadybugDB's COPY viable
+ * (scaled because the granule accounting inflates consumption on non-4K
+ * hosts, see granuleRatio); the upper bound means the hint can never exceed
+ * the page-size-scaled #2557 cap or 80% of RAM — and on a machine whose cap
+ * is below the COPY floor, the cap wins, so the pool is never over-committed.
+ * On 4 KiB hosts (ratio 1) this is byte-identical to clamping against the
+ * hintless default.
+ */
+const clampBufferPool = (bytes, pageSize = getOsPageSize()) => Math.min(scaledAnalyzePoolCap(pageSize), Math.max(ADAPTIVE_POOL_FLOOR * granuleRatio(pageSize), Math.floor(bytes)));
 /**
  * Buffer-pool bytes to provision per graph element (node + relationship).
  *
@@ -354,12 +411,18 @@ const clampBufferPool = (bytes) => Math.min(defaultBufferPoolSize(), Math.max(AD
 const POOL_BYTES_PER_ELEMENT = 4 * 1024;
 /**
  * Size the buffer pool to an estimated graph size (node + relationship count),
- * clamped to [ADAPTIVE_POOL_FLOOR, defaultBufferPoolSize()]. The estimate can
- * only *shrink* the pool from the default — never above the 2 GiB / 80%-RAM cap,
- * never below the COPY-safety floor — so no repo is under-sized or gets more
- * than the default it would have today.
+ * clamped to [ADAPTIVE_POOL_FLOOR, scaledAnalyzePoolCap], with every term
+ * scaled by granuleRatio (#2631): on non-4K hosts the engine bills pool
+ * budget per OS-page-sized granule, so the same graph consumes up to
+ * pageSize/4096 × the budget it needs on x86. On 4 KiB hosts the ratio is 1
+ * and this is byte-identical to the pre-#2631 behavior. The estimate is never
+ * above the page-size-scaled #2557 cap bounded by 80% of RAM, never below the
+ * scaled COPY-safety floor; the hintless default stays unscaled.
+ *
+ * `pageSize` is a test seam (the pageSizeDoctorLines convention); production
+ * callers omit it and get the memoized real OS page size.
  */
-export const estimateBufferPool = (graphElementCount) => clampBufferPool(graphElementCount * POOL_BYTES_PER_ELEMENT);
+export const estimateBufferPool = (graphElementCount, pageSize = getOsPageSize()) => clampBufferPool(graphElementCount * POOL_BYTES_PER_ELEMENT * granuleRatio(pageSize), pageSize);
 /**
  * Optional per-run buffer-pool size hint (bytes). The analyze orchestrator sets
  * it once the graph size is known (after the pipeline, before the DB open) so
@@ -394,10 +457,53 @@ const resolveBufferManagerSize = () => {
     // Non-empty but unparseable input: warn the operator and fall back —
     // mirrors the GITNEXUS_WAL_CHECKPOINT_THRESHOLD env path above.
     if (raw.trim().length > 0) {
-        logger.warn({ rawValue: raw, fallback: defaultBufferPoolSize() }, `Ignoring invalid GITNEXUS_LBUG_BUFFER_POOL_SIZE=${raw}; expected integer >= 0 (bytes; 0 restores the native 80%-of-RAM default); falling back to min(2 GiB, 80% of RAM).`);
+        logger.warn({ rawValue: raw, fallback: defaultBufferPoolSize() }, `Ignoring invalid GITNEXUS_LBUG_BUFFER_POOL_SIZE=${raw}; expected integer >= 0 (bytes; 0 restores the native 80%-of-RAM default); falling back to the platform default pool size.`);
     }
     return defaultBufferPoolSize();
 };
+/**
+ * Doctor-facing view of the pool size the next Database open would get
+ * (#2631): env override > clamped hint > unscaled hintless default. Read-only;
+ * doctor prints it next to the page-size lines so support triage sees the
+ * sizing inputs at a glance. `0` is the pass-through sentinel for LadybugDB's
+ * native 80%-of-RAM default — callers must label it, not print "0 MiB".
+ */
+export const getEffectiveBufferPoolSize = () => resolveBufferManagerSize();
+/**
+ * Matches the engine's buffer-pool exhaustion throw (buffer_manager.cpp:
+ * "Unable to allocate memory! The buffer pool is full and no memory could be
+ * freed!"). Distinct from isLbugPageSizeFrameError above, which matches the
+ * madvise/frame-release failure class.
+ */
+const BUFFER_POOL_EXHAUSTION_RE = /buffer pool is full|unable to allocate memory/i;
+const formatMiB = (bytes) => `${Math.round(bytes / (1024 * 1024))} MiB`;
+/**
+ * Actionable remedy for a buffer-pool exhaustion error (#2631), or undefined
+ * when `message` is not that class. Cause → consequence → remedy, the
+ * diagnoseExtensionLoad convention: names the effective pool, the override
+ * knob, and — on non-4K hosts — the granule amplification that makes the
+ * budget exhaust early (the reporter's Ascend/aarch64 64 KiB kernel billed a
+ * pool up to 16× faster than the same analyze on x86).
+ */
+export const bufferPoolExhaustionRemedy = (message, pageSize = getOsPageSize()) => {
+    if (!BUFFER_POOL_EXHAUSTION_RE.test(message))
+        return undefined;
+    const ratio = granuleRatio(pageSize);
+    const pool = resolveBufferManagerSize();
+    // 0 is the pass-through sentinel (GITNEXUS_LBUG_BUFFER_POOL_SIZE=0 →
+    // LadybugDB's native 80%-of-RAM default) — "0 MiB" would be nonsense in the
+    // very triage text this remedy exists to provide.
+    const poolLabel = pool === 0 ? "LadybugDB's native 80%-of-RAM default" : formatMiB(pool);
+    const pageNote = ratio > 1
+        ? ` This host's ${(pageSize ?? 0) / 1024} KiB OS page size makes the engine bill pool ` +
+            `memory in ${(pageSize ?? 0) / 1024} KiB granules — up to ${ratio}× faster budget use ` +
+            `than a 4 KiB-page host running the same analyze.`
+        : '';
+    return (`The LadybugDB buffer pool (${poolLabel}) was exhausted during the bulk COPY.` +
+        pageNote +
+        ` Set GITNEXUS_LBUG_BUFFER_POOL_SIZE=<bytes> to raise it (e.g. ${4 * 1024 * 1024 * 1024}` +
+        ` for 4 GiB); 0 restores LadybugDB's native 80%-of-RAM default.`);
+};
 /** Matches WAL corruption errors from the LadybugDB engine. */
 const WAL_CORRUPTION_RE = /corrupt(ed)?\s+wal|invalid\s+wal\s+record|wal.*corrupt|checksum.*wal/i;
 export const WAL_RECOVERY_SUGGESTION = 'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.';
@@ -478,8 +584,12 @@ const LBUG_PAGE_COMBO_RE = /unsupported page size combination/i;
  * True when `err` looks like the LadybugDB buffer manager failing to release
  * frame memory — the failure mode of a 4 KiB page-size assumption on a
  * 16 KiB/64 KiB-page kernel (#1231). Deliberately does NOT match the
- * generic "buffer pool is full" exhaustion error, which is a sizing
- * problem, not a page-size one.
+ * generic "buffer pool is full" exhaustion error: that one is handled as a
+ * SIZING problem — though since #2631 we know page size drives sizing too
+ * (the engine bills pool budget per OS-page-sized discard granule, so non-4K
+ * hosts exhaust the same budget up to pageSize/4096× earlier; see
+ * granuleRatio, which scales the pool accordingly, and
+ * bufferPoolExhaustionRemedy, which explains it to the operator).
  */
 export const isLbugPageSizeFrameError = (err) => {
     if (!err)
@@ -506,6 +616,15 @@ export const isPageSizeAwareLadybug = (version) => {
 // `undefined` = not probed yet; `null` = probed and unavailable. Cached
 // because analyze error paths and doctor may both ask, and getconf forks.
 let cachedOsPageSize;
+/**
+ * Test seam (the `_captureLogger` convention): pin the memoized OS page size
+ * so sizing tests are host-independent — without this they would silently
+ * drift on 16 KiB-page Apple Silicon runners. `number` pins a value, `null`
+ * pins "undetectable", `undefined` clears the memo so the next call re-probes.
+ */
+export const _setOsPageSizeForTests = (pageSize) => {
+    cachedOsPageSize = pageSize;
+};
 /**
  * OS memory page size in bytes, or `undefined` when it cannot be determined
  * (Windows, missing getconf, sandboxed exec). Node exposes no page-size API,
@@ -545,10 +664,6 @@ export const getOsPageSize = () => {
     }
     return cachedOsPageSize ?? undefined;
 };
-/** Exported only for unit tests — clears the getconf probe cache. */
-export const _resetOsPageSizeCacheForTest = () => {
-    cachedOsPageSize = undefined;
-};
 /**
  * Return true when the error message indicates that a LadybugDB write
  * transaction could not proceed due to lock contention — either a file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.10-rc.89",
+  "version": "1.6.10-rc.90",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",