gitnexus 1.6.10-rc.14 → 1.6.10-rc.16

package/dist/cli/analyze.js

@@ -14,11 +14,12 @@ import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { isLbugReady, LbugWipeError } from '../core/lbug/lbug-adapter.js';
 import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.js';
-import { isLbugCheckpointIoError, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
+import { getOsPageSize, isLbugCheckpointIoError, isLbugPageSizeFrameError, isPageSizeAwareLadybug, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir, getDefaultBranch } from '../storage/git.js';
 import { loadAnalyzeConfig, mergeAnalyzeOptions, resolveDefaultBranch, validateBranchName, GitNexusRcError, } from './analyze-config.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
+import { getRuntimeFingerprint } from '../core/platform/capabilities.js';
 import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
 import { warnMissingOptionalGrammars, getOptionalGrammarExtensions } from './optional-grammars.js';
 import { glob } from 'glob';
@@ -1252,6 +1253,48 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             process.exitCode = 1;
             return;
         }
+        // Buffer-manager frame-release failure on non-4K-page kernels (#1231).
+        // LadybugDB <= 0.17.x assumed 4 KiB OS pages when releasing evicted
+        // frames; Raspberry Pi 5 (16 KiB kernel pages) and other arm64 systems
+        // crash mid-COPY with a raw native message. 0.18.0 detects the page size
+        // at runtime, so the actionable fix depends on which side of that
+        // boundary the installed @ladybugdb/core is.
+        if (isLbugPageSizeFrameError(err)) {
+            const pageSize = getOsPageSize();
+            const ladybug = getRuntimeFingerprint().ladybugdb;
+            const pageLine = pageSize !== undefined && pageSize !== 4096
+                ? `  Detected OS page size: ${pageSize} bytes (non-4K — e.g. Raspberry Pi 5 16K kernel, Asahi Linux).\n`
+                : '';
+            // The upgrade variant must not assert version facts about an unknown
+            // version — mirror the doctor-side wording rule (#2424 review R2).
+            const upgradeIntro = ladybug === undefined
+                ? `  The installed @ladybugdb/core version is unknown — it may predate the\n` +
+                    `  runtime OS-page-size detection added in 0.18.0.\n`
+                : `  The installed @ladybugdb/core (${ladybug}) assumes 4 KiB pages in its buffer\n` +
+                    `  manager.\n`;
+            const guidance = isPageSizeAwareLadybug(ladybug)
+                ? `  The installed @ladybugdb/core (${ladybug}) already detects the OS page size at runtime,\n` +
+                    `  so this configuration was expected to work. Please report it:\n` +
+                    `    https://github.com/abhigyanpatwari/GitNexus/issues/1231\n` +
+                    `  and include: gitnexus --version, node --version, getconf PAGE_SIZE, uname -a,\n` +
+                    `  and the full error message above.\n`
+                : upgradeIntro +
+                    `  Upgrade GitNexus to a release that bundles @ladybugdb/core >= 0.18.0\n` +
+                    `  (gitnexus >= 1.6.9), which detects the OS page size at runtime:\n` +
+                    `    npm install -g gitnexus@latest\n` +
+                    `  Last-resort workaround on Raspberry Pi 5: boot the 4 KiB-page kernel\n` +
+                    `  (config.txt: kernel=kernel8.img), at the cost of Pi 5 optimizations.\n`;
+            // Embed the raw native text (indented, no stack) so "the full error
+            // message above" is fulfillable — same idiom as the LbugWipeError
+            // branch. The errno suffix and the 0.18.0 guard's frame/granule numbers
+            // are the discriminating triage content (#2424 review P2).
+            cliError(`  LadybugDB's buffer manager failed to release frame memory.\n` +
+                `    ${msg.replace(/\n/g, '\n    ')}\n` +
+                pageLine +
+                guidance, { recoveryHint: 'lbug-page-size', pageSize, ladybugVersion: ladybug });
+            process.exitCode = 1;
+            return;
+        }
         // Local embedding runtime unsupported on this platform (macOS Intel ships no
         // darwin/x64 ONNX native binding, #1515). The guard threw before importing
         // transformers.js, so this is a clean, actionable GitNexus message. Checked

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

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'lbug-wipe-failed' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'lbug-wipe-failed' | 'lbug-page-size' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/doctor.d.ts

@@ -23,4 +23,17 @@ export declare function localEmbeddingDoctorStatus(opts: {
     status: string;
     detail: string | null;
 };
+/**
+ * Page-size lines for the `doctor` Runtime section (#1231). Pure so the
+ * warning gate can be unit-tested without running the whole command (the
+ * `localEmbeddingDoctorStatus` precedent above) — but takes the probed
+ * values as plain params rather than injectable probes, because `undefined`
+ * is a *meaningful* pageSize state here (probe unavailable / win32) and
+ * would collide with a "not provided → use default" DI convention.
+ *
+ * Returns 0 lines (page size unknown), 1 line (page size), or 2 lines
+ * (page size + non-4K warning when the installed @ladybugdb/core does not
+ * detect the OS page size at runtime).
+ */
+export declare function pageSizeDoctorLines(pageSize: number | undefined, ladybugVersion: string | undefined): string[];
 export declare const doctorCommand: () => Promise<void>;

package/dist/cli/doctor.js

@@ -5,6 +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 } from '../core/lbug/native-check.js';
+import { 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';
@@ -87,6 +88,33 @@ export function localEmbeddingDoctorStatus(opts) {
     }
     return { status: '✓ local embeddings supported', detail: null };
 }
+/**
+ * Page-size lines for the `doctor` Runtime section (#1231). Pure so the
+ * warning gate can be unit-tested without running the whole command (the
+ * `localEmbeddingDoctorStatus` precedent above) — but takes the probed
+ * values as plain params rather than injectable probes, because `undefined`
+ * is a *meaningful* pageSize state here (probe unavailable / win32) and
+ * would collide with a "not provided → use default" DI convention.
+ *
+ * Returns 0 lines (page size unknown), 1 line (page size), or 2 lines
+ * (page size + non-4K warning when the installed @ladybugdb/core does not
+ * detect the OS page size at runtime).
+ */
+export function pageSizeDoctorLines(pageSize, ladybugVersion) {
+    if (pageSize === undefined)
+        return [];
+    const lines = [`  ${padDisplayEnd('page size', 10)}${pageSize}`];
+    if (pageSize > 4096 && !isPageSizeAwareLadybug(ladybugVersion)) {
+        // Don't assert "< 0.18.0" as fact when the version is unresolvable
+        // (#2424 review R2) — name the unknown state instead.
+        const versionClause = ladybugVersion === undefined
+            ? 'an unknown @ladybugdb/core version (may predate 0.18.0)'
+            : `@ladybugdb/core < 0.18.0`;
+        lines.push(`  ${padDisplayEnd('', 10)}⚠ non-4K page size with ${versionClause} — ` +
+            `'gitnexus analyze' may fail during COPY (#1231). Upgrade gitnexus (npm install -g gitnexus@latest).`);
+    }
+    return lines;
+}
 export const doctorCommand = async () => {
     const fingerprint = getRuntimeFingerprint();
     const capabilities = getRuntimeCapabilities();
@@ -97,6 +125,13 @@ export const doctorCommand = async () => {
     console.log(`  ${label('doctor.labels.node', 10)}${fingerprint.node}`);
     console.log(`  ${label('doctor.labels.gitnexus', 10)}${fingerprint.gitnexus}`);
     console.log(`  ${label('doctor.labels.ladybugdb', 10)}${fingerprint.ladybugdb ?? 'unknown'}`);
+    // OS page size next to the LadybugDB version because the two interact:
+    // @ladybugdb/core < 0.18.0 assumed 4 KiB pages in its buffer manager and
+    // crashes mid-COPY on 16 KiB/64 KiB-page kernels (#1231). Literal label
+    // (like the 'native' line below) to avoid adding i18n keys.
+    for (const line of pageSizeDoctorLines(getOsPageSize(), fingerprint.ladybugdb)) {
+        console.log(line);
+    }
     const nativeCheck = checkLbugNative();
     if (nativeCheck.ok) {
         console.log(`  ${padDisplayEnd('native', 10)}✓ lbugjs.node loaded`);

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

@@ -62,6 +62,31 @@ export declare function isWalCorruptionError(err: unknown): boolean;
  * back to the permissive matcher.
  */
 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.
+ */
+export declare const isLbugPageSizeFrameError: (err: unknown) => boolean;
+/**
+ * True when the given `@ladybugdb/core` version contains the runtime
+ * OS-page-size detection introduced in 0.18.0 (see the matcher comment
+ * above). Unknown/unparseable versions return false so callers err on the
+ * side of showing the upgrade hint.
+ */
+export declare const isPageSizeAwareLadybug: (version: string | undefined) => boolean;
+/**
+ * OS memory page size in bytes, or `undefined` when it cannot be determined
+ * (Windows, missing getconf, sandboxed exec). Node exposes no page-size API,
+ * so this shells out to POSIX `getconf PAGE_SIZE` — same execFileSync shape
+ * as the Windows 8.3 short-path probe above, but with a tighter timeout and
+ * 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

@@ -337,6 +337,106 @@ export const isLbugCheckpointIoError = (err) => {
         return true;
     return LBUG_CHECKPOINT_PERMISSIVE_RE.test(msg);
 };
+// ─── Ladybug non-4K page-size frame-release matcher (#1231) ─────────────────
+//
+// LadybugDB <= 0.17.x hardcoded a 4 KiB OS-page assumption in its buffer
+// manager: evicting a frame released physical memory with
+// `madvise(frame, frameSize, MADV_DONTNEED)` on 4 KiB-aligned frame
+// addresses (verified by disassembling `VMRegion::releaseFrame` in
+// @ladybugdb/core-linux-arm64 0.17.1 — `mov w2, #0x4` = MADV_DONTNEED,
+// throw on non-zero return). On kernels with 16 KiB pages (Raspberry Pi 5
+// default 2712 kernel, Asahi Linux) or 64 KiB pages (some enterprise arm64
+// distros), madvise rejects addresses that are not multiples of the real
+// page size with EINVAL, surfacing as:
+//   "Buffer manager exception: Releasing physical memory associated with a
+//    frame failed with error code -1: Invalid argument."
+// which aborts `gitnexus analyze` mid-COPY.
+//
+// @ladybugdb/core 0.18.0 rewrote the release path with runtime OS-page-size
+// detection and discard-granule-aligned madvise (new binary strings:
+// "Failed to detect the operating system page size.", "Unsupported page
+// size combination: frame size {}, discard granule size {}, frame group
+// size {}."), so upgrading is the fix. The residual 0.18.0 guard
+// ("Unsupported page size combination") is matched here too so exotic
+// configurations receive the same actionable guidance instead of a raw
+// native message.
+const LBUG_FRAME_RELEASE_RE = /releasing physical memory associated with a frame failed/i;
+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.
+ */
+export const isLbugPageSizeFrameError = (err) => {
+    if (!err)
+        return false;
+    const msg = err instanceof Error ? err.message : String(err);
+    return LBUG_FRAME_RELEASE_RE.test(msg) || LBUG_PAGE_COMBO_RE.test(msg);
+};
+/**
+ * True when the given `@ladybugdb/core` version contains the runtime
+ * OS-page-size detection introduced in 0.18.0 (see the matcher comment
+ * above). Unknown/unparseable versions return false so callers err on the
+ * side of showing the upgrade hint.
+ */
+export const isPageSizeAwareLadybug = (version) => {
+    if (!version)
+        return false;
+    const m = /^(\d+)\.(\d+)/.exec(version.trim());
+    if (!m)
+        return false;
+    const major = Number(m[1]);
+    const minor = Number(m[2]);
+    return major > 0 || minor >= 18;
+};
+// `undefined` = not probed yet; `null` = probed and unavailable. Cached
+// because analyze error paths and doctor may both ask, and getconf forks.
+let cachedOsPageSize;
+/**
+ * OS memory page size in bytes, or `undefined` when it cannot be determined
+ * (Windows, missing getconf, sandboxed exec). Node exposes no page-size API,
+ * so this shells out to POSIX `getconf PAGE_SIZE` — same execFileSync shape
+ * as the Windows 8.3 short-path probe above, but with a tighter timeout and
+ * an explicit killSignal (see the options comment below).
+ */
+export const getOsPageSize = () => {
+    if (cachedOsPageSize !== undefined)
+        return cachedOsPageSize ?? undefined;
+    if (process.platform === 'win32') {
+        // Windows allocation granularity is not what madvise alignment is about;
+        // the #1231 failure mode is POSIX-only.
+        cachedOsPageSize = null;
+        return undefined;
+    }
+    try {
+        // killSignal SIGKILL (first use in this repo): the default SIGTERM is
+        // catchable, so a signal-trapping child held the "5s" timeout for 9s in
+        // review reproduction — SIGKILL makes the timeout real for everything
+        // except a child stuck in uninterruptible I/O (D state). 2000ms, not
+        // 5000: doctor runs this probe on its happy path and real getconf
+        // answers in ~2ms, but keep margin for loaded Pi-class hardware — a
+        // too-tight ceiling would silently drop the very #1231 diagnostics this
+        // probe exists to provide (the catch caches the failure). (#2424 review)
+        const out = execFileSync('getconf', ['PAGE_SIZE'], {
+            encoding: 'utf-8',
+            timeout: 2000,
+            killSignal: 'SIGKILL',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const parsed = Number(out.trim());
+        cachedOsPageSize = Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+    }
+    catch {
+        cachedOsPageSize = null;
+    }
+    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.14",
+  "version": "1.6.10-rc.16",
   "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",

package/scripts/cross-platform-tests.ts

@@ -36,6 +36,10 @@ const PLATFORM_LOGIC = [
   // must exercise the Windows backslash branch, so run it on the OS matrix (#2394).
   'test/unit/cli-entry.test.ts',
   'test/unit/platform-capabilities.test.ts',
+  // getconf page-size probe: explicit process.platform gate (win32 short-circuit)
+  // plus a live-probe test whose only real non-4K coverage is macos-arm64's
+  // 16 KiB pages — the exact hardware class #1231 targets (#2424 review).
+  'test/unit/lbug-config-pagesize.test.ts',
   'test/unit/worker-pool-windows-quarantine.test.ts',
   'test/unit/lbug-pool-fts-load.test.ts',
   'test/unit/repo-manager.test.ts',