gitnexus 1.6.9 → 1.6.10-aptos.1

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

@@ -39,8 +39,15 @@ export declare function resolveNativeSafeStorageDir(storagePath: string, subdir:
  *    `true` (0.16.0). Existing call sites that relied on the positional
  *    default must now pass `false` explicitly to preserve behaviour.
  *
- * Putting both in one shared module guarantees every `new lbug.Database(...)`
- * call site agrees on the same ceiling and behaviour.
+ * 3. `bufferManagerSize` (not a 0.16.0 change, same pin-explicitly
+ *    principle): `0` means "native default", and the native default buffer
+ *    pool is 80% of physical RAM. A long-lived `gitnexus mcp` process or a
+ *    large incremental analyze can balloon to that ceiling and OOM-kill the
+ *    host session (#2557), so GitNexus pins an explicit bounded pool — see
+ *    `resolveBufferManagerSize`.
+ *
+ * Putting these in one shared module guarantees every `new lbug.Database(...)`
+ * call site agrees on the same ceilings and behaviour.
  */
 /**
  * Upper bound for any single GitNexus LadybugDB file (graph index, group
@@ -54,6 +61,16 @@ export declare function resolveNativeSafeStorageDir(storagePath: string, subdir:
  */
 export declare const LBUG_MAX_DB_SIZE: number;
 export declare const parseWalCheckpointThreshold: (raw: string | undefined) => number | undefined;
+/**
+ * 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.
+ */
+export declare const estimateBufferPool: (graphElementCount: number) => number;
+/** Set (bytes) or clear (`undefined`) the per-run buffer-pool size hint. */
+export declare const setBufferPoolSizeHint: (bytes: number | undefined) => void;
 export declare const WAL_RECOVERY_SUGGESTION = "WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.";
 export declare function isWalCorruptionError(err: unknown): boolean;
 /**
@@ -62,6 +79,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;
@@ -86,6 +128,15 @@ export interface LbugConnectionHandle {
  * import directly from this module — no re-export to keep in sync.
  */
 export declare const isDbBusyError: (err: unknown) => boolean;
+/**
+ * True when a WAL-checkpoint IO error ALSO carries a busy/lock signal — the
+ * rotation failed because another handle (a `gitnexus mcp` server, or this
+ * process's own reader) holds the store's WAL open, rather than a permanent
+ * disk error. Reuses `isDbBusyError`'s already-tested keyword set instead of a
+ * fresh regex, so an unmatched message degrades to "IO error" rather than
+ * silently claiming a held-open cause. (#2599)
+ */
+export declare const isLbugCheckpointBusyError: (err: unknown) => boolean;
 /** See {@link classifyDeleteAllError}. */
 export type DeleteAllErrorClass = 'benign-missing-table' | 'rethrow';
 /**
@@ -108,6 +159,8 @@ export type DeleteAllErrorClass = 'benign-missing-table' | 'rethrow';
  */
 export declare const classifyDeleteAllError: (err: unknown) => DeleteAllErrorClass;
 export declare function createLbugDatabase(lbugModule: LbugModule, databasePath: string, options?: LbugDatabaseOptions): lbug.Database;
+export declare const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
+export declare const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
 /**
  * Marker symbol attached to lock errors after `openWithLockRetry` exhausts
  * its budget. `withLbugDb`'s outer query-time retry consults this so it
@@ -121,6 +174,7 @@ export declare const LBUG_OPEN_RETRY_EXHAUSTED: unique symbol;
 export declare const isOpenRetryExhausted: (err: unknown) => boolean;
 /** Exported only for direct unit testing — production callers use `openWithLockRetry`. */
 export declare const _isTestFixturePathForTest: (dbPath: string) => boolean;
+export declare const sleep: (ms: number) => Promise<void>;
 export declare function openLbugConnection(lbugModule: LbugModule, databasePath: string, options?: LbugDatabaseOptions): Promise<LbugConnectionHandle>;
 export declare function closeLbugConnection(handle: LbugConnectionHandle): Promise<void>;
 /**

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

@@ -227,8 +227,15 @@ export function resolveNativeSafeStorageDir(storagePath, subdir) {
  *    `true` (0.16.0). Existing call sites that relied on the positional
  *    default must now pass `false` explicitly to preserve behaviour.
  *
- * Putting both in one shared module guarantees every `new lbug.Database(...)`
- * call site agrees on the same ceiling and behaviour.
+ * 3. `bufferManagerSize` (not a 0.16.0 change, same pin-explicitly
+ *    principle): `0` means "native default", and the native default buffer
+ *    pool is 80% of physical RAM. A long-lived `gitnexus mcp` process or a
+ *    large incremental analyze can balloon to that ceiling and OOM-kill the
+ *    host session (#2557), so GitNexus pins an explicit bounded pool — see
+ *    `resolveBufferManagerSize`.
+ *
+ * Putting these in one shared module guarantees every `new lbug.Database(...)`
+ * call site agrees on the same ceilings and behaviour.
  */
 /**
  * Upper bound for any single GitNexus LadybugDB file (graph index, group
@@ -286,6 +293,116 @@ const resolveCheckpointThreshold = () => {
     }
     return DEFAULT_WAL_CHECKPOINT_THRESHOLD;
 };
+/**
+ * Default ceiling for the LadybugDB buffer pool in bytes (#2557).
+ *
+ * The pool is a page cache with eviction, so the ceiling trades throughput
+ * on very large working sets for a machine that stays alive: 2 GiB is
+ * ~40× the GitNexus self-index, while the native 80%-of-RAM default let a
+ * `detect_changes` call grow a 105 MiB on-disk index to 19.5 GiB RSS and
+ * OOM-kill the reporter's session. The `min` with 80% of `os.totalmem()`
+ * keeps sub-2.5-GiB machines at the native-equivalent bound (no regression
+ * there); the 64 MiB floor keeps tiny containers above any plausible
+ * native minimum pool size.
+ */
+const DEFAULT_BUFFER_POOL_CAP = 2 * 1024 * 1024 * 1024;
+const BUFFER_POOL_FLOOR = 64 * 1024 * 1024;
+// COPY-safety floor for the adaptive hint (below). LadybugDB's bulk COPY needs
+// working buffer-pool memory that scales with the repo: a 64 MiB pool fails
+// ("buffer pool is full and no memory could be freed") on any non-trivial repo,
+// and even the ~1800-file GitNexus checkout needs ≥256 MiB. COPY working
+// memory also scales with schema width (buffer pages are held per column):
+// the Move node tables (main-aptos) add dozens of columns across Function/
+// Struct/Enum/EnumVariant/Const/Module, and a 256 MiB pool deterministically
+// fails their COPY on @ladybugdb/core 0.18.3 even for tiny fixtures
+// (incremental-dirty-recovery reproduces it; 512 MiB passes). So the adaptive
+// size never drops a repo below this — a distinct, higher floor than
+// BUFFER_POOL_FLOOR, which only guards defaultBufferPoolSize on tiny-RAM
+// machines. It is still clamped up to defaultBufferPoolSize, so a machine whose
+// default is below this floor keeps its default rather than over-committing.
+const ADAPTIVE_POOL_FLOOR = 512 * 1024 * 1024;
+const parseBufferPoolSize = (raw) => {
+    if (raw === undefined)
+        return undefined;
+    const normalized = raw.trim();
+    if (normalized.length === 0)
+        return undefined;
+    const parsed = Number(normalized);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return undefined;
+    return Math.floor(parsed);
+};
+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.
+ */
+const clampBufferPool = (bytes) => Math.min(defaultBufferPoolSize(), Math.max(ADAPTIVE_POOL_FLOOR, Math.floor(bytes)));
+/**
+ * Buffer-pool bytes to provision per graph element (node + relationship).
+ *
+ * The fixed 2 GiB default is far larger than most repos' working set, and
+ * LadybugDB eagerly commits the pool at DB open — measured: a full
+ * `analyze --force` of the GitNexus checkout takes ~51 s with the 2 GiB pool
+ * vs ~35 s with the ~414 MiB this factor yields (31% faster; the oversized
+ * pool's commit dominates). The pool is a page cache over the on-disk index,
+ * which scales with node/edge count, so a per-element budget sizes it to the
+ * repo. Kept generous so the whole index stays resident (no COPY thrash) and
+ * always clamped to at least ADAPTIVE_POOL_FLOOR; tuned by timing a real
+ * large-repo `analyze --force` at this factor vs a forced 2 GiB pool (the pool
+ * is a native eager allocation, measured with a real analyze, not a build-free
+ * bench — see the emit-path COPY timing note in bench/emit-persistence).
+ */
+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.
+ */
+export const estimateBufferPool = (graphElementCount) => clampBufferPool(graphElementCount * POOL_BYTES_PER_ELEMENT);
+/**
+ * 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
+ * the pool is sized to the repo instead of the fixed 2 GiB default, and clears
+ * it at run end. Non-analyze opens (MCP serve, `native-check` `:memory:`) never
+ * set it and keep the default.
+ */
+let bufferPoolSizeHint;
+/** Set (bytes) or clear (`undefined`) the per-run buffer-pool size hint. */
+export const setBufferPoolSizeHint = (bytes) => {
+    bufferPoolSizeHint = bytes;
+};
+/**
+ * Resolve the `bufferManagerSize` passed to every `new lbug.Database(...)`.
+ * `GITNEXUS_LBUG_BUFFER_POOL_SIZE` (bytes) overrides everything; `0` is a
+ * deliberate escape hatch that restores LadybugDB's native unbounded
+ * 80%-of-RAM default. With no env override, a per-run `setBufferPoolSizeHint`
+ * (clamped to [floor, default]) sizes the pool to the repo; otherwise the
+ * default. Resolved at call time (not module load) so tests can stub the env
+ * var, the hint, and `os.totalmem`.
+ */
+const resolveBufferManagerSize = () => {
+    const raw = process.env.GITNEXUS_LBUG_BUFFER_POOL_SIZE;
+    if (raw === undefined) {
+        return bufferPoolSizeHint !== undefined
+            ? clampBufferPool(bufferPoolSizeHint)
+            : defaultBufferPoolSize();
+    }
+    const parsed = parseBufferPoolSize(raw);
+    if (parsed !== undefined)
+        return parsed;
+    // 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).`);
+    }
+    return defaultBufferPoolSize();
+};
 /** 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.';
@@ -337,6 +454,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
@@ -370,6 +587,27 @@ export const isDbBusyError = (err) => {
         msg.includes('already in use') ||
         msg.includes('only one write transaction at a time'));
 };
+/**
+ * True when a WAL-checkpoint IO error ALSO carries a busy/lock signal — the
+ * rotation failed because another handle (a `gitnexus mcp` server, or this
+ * process's own reader) holds the store's WAL open, rather than a permanent
+ * disk error. Reuses `isDbBusyError`'s already-tested keyword set instead of a
+ * fresh regex, so an unmatched message degrades to "IO error" rather than
+ * silently claiming a held-open cause. (#2599)
+ */
+export const isLbugCheckpointBusyError = (err) => {
+    if (!isLbugCheckpointIoError(err))
+        return false;
+    // Anchor to real held-open wording rather than isDbBusyError's broad
+    // `.includes('lock')`, which matches the DB PATH embedded in the checkpoint
+    // error message (e.g. a repo under `blockchain-app`) and would misclassify a
+    // pure disk fault as held-open (#2614 LOW).
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (msg.includes('could not set lock') ||
+        msg.includes('lock is held') ||
+        msg.includes('being used by another process') ||
+        msg.includes('is busy'));
+};
 /**
  * Classify an error thrown while clearing all relationships of one type
  * before an incremental re-write (`deleteAllRelationshipsOfType` in
@@ -396,7 +634,7 @@ export const classifyDeleteAllError = (err) => {
 };
 export function createLbugDatabase(lbugModule, databasePath, options = {}) {
     // .d.ts declares fewer args than the native constructor accepts.
-    return new lbugModule.Database(databasePath, 0, // bufferManagerSize
+    return new lbugModule.Database(databasePath, resolveBufferManagerSize(), // bufferManagerSize (#2557: default min(2 GiB, 80% RAM); GITNEXUS_LBUG_BUFFER_POOL_SIZE overrides; 0 restores the native 80%-of-RAM default)
     false, // enableCompression (pinned for v0.16.0)
     options.readOnly ?? false, LBUG_MAX_DB_SIZE, true, // autoCheckpoint (always on)
     resolveCheckpointThreshold(), // checkpointThreshold (default 64 MiB; override with GITNEXUS_WAL_CHECKPOINT_THRESHOLD; -1 keeps Ladybug stock ~16 MiB)
@@ -411,7 +649,10 @@ export function createLbugDatabase(lbugModule, databasePath, options = {}) {
 //   1. OPEN_LOCK_RETRY_ATTEMPTS / OPEN_LOCK_RETRY_DELAY_MS  (this file)
 //      → `new lbug.Database()` constructor lock failures
 //   2. HANDLE_RELEASE_PROBE_ATTEMPTS / HANDLE_RELEASE_PROBE_DELAY_MS  (this file)
-//      → post-close fs.open probe to absorb Windows handle-release lag
+//      → post-close fs.open probe to absorb Windows handle-release lag; also
+//        the shared budget for wipeLbugDbFiles' ENOENT-verified removal
+//        (lbug-adapter.ts) and the dirty-recovery sidecar park's
+//        rename/rm retries (sidecar-recovery.ts) — same lock class
 //   3. DB_LOCK_RETRY_ATTEMPTS / DB_LOCK_RETRY_DELAY_MS  (lbug-adapter.ts withLbugDb)
 //      → query-time busy/lock retry around already-open connections
 //
@@ -429,9 +670,26 @@ export function createLbugDatabase(lbugModule, databasePath, options = {}) {
 // matches on is unchanged.)
 const OPEN_LOCK_RETRY_ATTEMPTS = 5;
 const OPEN_LOCK_RETRY_DELAY_MS = 100;
-const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
-const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
+// Exported (this shipping review, FIX 1/2): the dirty-recovery sidecar park
+// (sidecar-recovery.ts) and the ENOENT-verified wipe (lbug-adapter.ts
+// wipeLbugDbFiles) retry the SAME Windows handle-release/AV lock class, and
+// their previous private mirror constants were documentation-coupled copies
+// that could drift from this tuning-knob registry silently.
+export const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
+export const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
 const HANDLE_RELEASE_LOCK_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
+// Retry-budget registry, part 2 (retry-budget consolidation): the remaining
+// open-time lock retries live next to their call sites but are catalogued here
+// so all lbug retry budgets surface in one grep. They retry the same lock class
+// as 1–3 ("Could not set lock" while a writer rebuilds the index):
+//   4. LOCK_RETRY_ATTEMPTS / LOCK_RETRY_DELAY_MS  (pool-adapter.ts)
+//      → read pool's read-only open while `gitnexus analyze` is writing
+//        (3 attempts, linear 2s·n back-off ≈ 6s total)
+//   5. LBUG_OPEN_RETRY_ATTEMPTS / _BASE_MS / _MAX_MS  (group/bridge-db.ts)
+//      → cross-repo bridge RO open race (10 attempts, linear 100ms·n capped
+//        at 500ms ≈ 3.5s total)
+// Kept in-file (not moved here) so explicit `lbug-config` test mocks don't have
+// to enumerate them; change a budget in its call site and update this catalogue.
 /**
  * Test-fixture directory prefixes recognized by `isTestFixturePath`.
  *
@@ -492,7 +750,9 @@ const isTestFixturePath = (dbPath) => {
 };
 /** Exported only for direct unit testing — production callers use `openWithLockRetry`. */
 export const _isTestFixturePathForTest = isTestFixturePath;
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Exported alongside HANDLE_RELEASE_PROBE_* (this shipping review, FIX 1/2)
+// so the consumers of the shared retry budget do not each grow a private copy.
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * Attempt to remove stale `.wal` / `.lock` sidecars that a previous aborted
  * test run may have left behind. Best-effort: ENOENT is normal, anything

package/dist/core/lbug/move-columns.d.ts

@@ -0,0 +1,7 @@
+export declare const CODE_ELEMENT_COLUMNS: readonly ["id", "name", "filePath", "startLine", "endLine", "isExported", "content", "description"];
+export declare const MULTI_LANG_BASE_COLUMNS: readonly ["id", "name", "filePath", "startLine", "endLine", "content", "description"];
+export declare const MOVE_FUNCTION_COLUMNS: readonly ["id", "name", "filePath", "startLine", "endLine", "isExported", "content", "description", "language", "qualifiedName", "moduleQualifiedName", "visibility", "visibilityModifier", "isEntry", "isView", "isInline", "isNative", "parameterCount", "returnType", "acquires", "usedTypes", "attributes", "attributesJson", "typeParamsJson", "locationFidelity"];
+export declare const MOVE_STRUCT_LIKE_COLUMNS: readonly ["id", "name", "filePath", "startLine", "endLine", "content", "description", "language", "qualifiedName", "moduleQualifiedName", "moduleAddress", "abilities", "isResource", "isEvent", "fieldList", "attributes", "attributesJson", "typeParamsJson", "moveDeclarationKind", "locationFidelity"];
+export declare const MOVE_ENUM_VARIANT_COLUMNS: readonly ["id", "name", "filePath", "startLine", "endLine", "content", "description", "language", "qualifiedName", "parentEnum", "moduleQualifiedName", "variantKind", "fieldsJson", "attributes", "attributesJson", "locationFidelity"];
+export declare const MOVE_CONST_COLUMNS: readonly ["id", "name", "filePath", "startLine", "endLine", "content", "description", "language", "qualifiedName", "moduleQualifiedName", "constType", "constValue", "isErrorCode", "locationFidelity"];
+export declare const MOVE_MODULE_COLUMNS: readonly ["id", "name", "filePath", "startLine", "endLine", "content", "description", "language", "qualifiedName", "moduleAddress", "attributes", "attributesJson", "locationFidelity"];

package/dist/core/lbug/move-columns.js

@@ -0,0 +1,86 @@
+export const CODE_ELEMENT_COLUMNS = [
+    'id',
+    'name',
+    'filePath',
+    'startLine',
+    'endLine',
+    'isExported',
+    'content',
+    'description',
+];
+export const MULTI_LANG_BASE_COLUMNS = [
+    'id',
+    'name',
+    'filePath',
+    'startLine',
+    'endLine',
+    'content',
+    'description',
+];
+export const MOVE_FUNCTION_COLUMNS = [
+    ...CODE_ELEMENT_COLUMNS,
+    'language',
+    'qualifiedName',
+    'moduleQualifiedName',
+    'visibility',
+    'visibilityModifier',
+    'isEntry',
+    'isView',
+    'isInline',
+    'isNative',
+    'parameterCount',
+    'returnType',
+    'acquires',
+    'usedTypes',
+    'attributes',
+    'attributesJson',
+    'typeParamsJson',
+    'locationFidelity',
+];
+export const MOVE_STRUCT_LIKE_COLUMNS = [
+    ...MULTI_LANG_BASE_COLUMNS,
+    'language',
+    'qualifiedName',
+    'moduleQualifiedName',
+    'moduleAddress',
+    'abilities',
+    'isResource',
+    'isEvent',
+    'fieldList',
+    'attributes',
+    'attributesJson',
+    'typeParamsJson',
+    'moveDeclarationKind',
+    'locationFidelity',
+];
+export const MOVE_ENUM_VARIANT_COLUMNS = [
+    ...MULTI_LANG_BASE_COLUMNS,
+    'language',
+    'qualifiedName',
+    'parentEnum',
+    'moduleQualifiedName',
+    'variantKind',
+    'fieldsJson',
+    'attributes',
+    'attributesJson',
+    'locationFidelity',
+];
+export const MOVE_CONST_COLUMNS = [
+    ...MULTI_LANG_BASE_COLUMNS,
+    'language',
+    'qualifiedName',
+    'moduleQualifiedName',
+    'constType',
+    'constValue',
+    'isErrorCode',
+    'locationFidelity',
+];
+export const MOVE_MODULE_COLUMNS = [
+    ...MULTI_LANG_BASE_COLUMNS,
+    'language',
+    'qualifiedName',
+    'moduleAddress',
+    'attributes',
+    'attributesJson',
+    'locationFidelity',
+];

package/dist/core/lbug/native-check.d.ts

@@ -4,3 +4,43 @@ export interface NativeCheckResult {
     message?: string;
 }
 export declare function checkLbugNative(overridePkgDir?: string): NativeCheckResult;
+export interface FtsProbeResult {
+    loaded: boolean;
+    /** Collapsed LadybugDB error when `loaded` is false. */
+    reason?: string;
+}
+/** Same shape for every optional extension; `FtsProbeResult` is the legacy name. */
+export type ExtensionProbeResult = FtsProbeResult;
+/**
+ * Live-probe `LOAD EXTENSION fts` on a throwaway in-memory database.
+ *
+ * `doctor` used to print the static platform capability, which contradicted
+ * analyze whenever the extension file was missing or unloadable (#2374).
+ * LOAD never touches the network, so the probe is safe offline, and it
+ * surfaces LadybugDB's real error — which distinguishes a missing extension
+ * file from a present-but-broken one (wrong platform, truncated download).
+ * Dynamic import so doctor still runs when the native module itself is broken.
+ *
+ * Bounded by `timeoutMs`: an unresponsive extension file (e.g. on a hung
+ * network home dir) must never freeze `doctor` — the tool the degradation
+ * warnings send users to. `Promise.race` lets doctor report and move on; it
+ * cannot cancel an in-flight native call, so a future thread-blocking case
+ * would need an out-of-process probe.
+ */
+export declare function probeFtsExtensionLoad(timeoutMs?: number): Promise<FtsProbeResult>;
+/**
+ * Live-probe `LOAD EXTENSION vector`, the VECTOR counterpart of the FTS probe.
+ *
+ * Needed for the same reason #2374 needed the FTS one, and reported the same
+ * way: #2623's reporter saw `doctor` print `VECTOR index: available` while
+ * every incremental `analyze` was dying because the extension had not loaded.
+ * `doctor` derived that line from a static platform capability, so it read
+ * "available" no matter what the extension file was doing.
+ *
+ * Probes for real on every platform, Windows included: the extension server
+ * ships win_amd64 VECTOR artifacts for every 0.18.x extension version (the
+ * old blanket Windows refusal was stale, #1365-era). LOAD never touches the
+ * network and never invokes the installer, so this probe is exactly as safe
+ * as the FTS one above.
+ */
+export declare function probeVectorExtensionLoad(timeoutMs?: number): Promise<ExtensionProbeResult>;

package/dist/core/lbug/native-check.js

@@ -81,3 +81,93 @@ export function checkLbugNative(overridePkgDir) {
     }
     return { ok: true, binaryPath };
 }
+const DEFAULT_FTS_PROBE_TIMEOUT_MS = 10_000;
+/** Close each result, swallowing close-time errors so a successful LOAD is not
+ *  misreported as a failure (native-check keeps no static lbug dependency, so it
+ *  cannot reuse the adapter's closeQueryResults — that would eagerly load the
+ *  module and defeat the dynamic import below). */
+const closeProbeResults = (result) => {
+    for (const r of Array.isArray(result) ? result : [result]) {
+        try {
+            r?.close?.();
+        }
+        catch {
+            // ignore — a close failure must not flip a successful LOAD to failed
+        }
+    }
+};
+/**
+ * Live-probe `LOAD EXTENSION fts` on a throwaway in-memory database.
+ *
+ * `doctor` used to print the static platform capability, which contradicted
+ * analyze whenever the extension file was missing or unloadable (#2374).
+ * LOAD never touches the network, so the probe is safe offline, and it
+ * surfaces LadybugDB's real error — which distinguishes a missing extension
+ * file from a present-but-broken one (wrong platform, truncated download).
+ * Dynamic import so doctor still runs when the native module itself is broken.
+ *
+ * Bounded by `timeoutMs`: an unresponsive extension file (e.g. on a hung
+ * network home dir) must never freeze `doctor` — the tool the degradation
+ * warnings send users to. `Promise.race` lets doctor report and move on; it
+ * cannot cancel an in-flight native call, so a future thread-blocking case
+ * would need an out-of-process probe.
+ */
+export async function probeFtsExtensionLoad(timeoutMs = DEFAULT_FTS_PROBE_TIMEOUT_MS) {
+    return await probeExtensionLoad('fts', timeoutMs);
+}
+/**
+ * Live-probe `LOAD EXTENSION vector`, the VECTOR counterpart of the FTS probe.
+ *
+ * Needed for the same reason #2374 needed the FTS one, and reported the same
+ * way: #2623's reporter saw `doctor` print `VECTOR index: available` while
+ * every incremental `analyze` was dying because the extension had not loaded.
+ * `doctor` derived that line from a static platform capability, so it read
+ * "available" no matter what the extension file was doing.
+ *
+ * Probes for real on every platform, Windows included: the extension server
+ * ships win_amd64 VECTOR artifacts for every 0.18.x extension version (the
+ * old blanket Windows refusal was stale, #1365-era). LOAD never touches the
+ * network and never invokes the installer, so this probe is exactly as safe
+ * as the FTS one above.
+ */
+export async function probeVectorExtensionLoad(timeoutMs = DEFAULT_FTS_PROBE_TIMEOUT_MS) {
+    return await probeExtensionLoad('vector', timeoutMs);
+}
+/**
+ * Shared LOAD probe. `extension` is a fixed internal literal, never user input.
+ */
+async function probeExtensionLoad(extension, timeoutMs) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({
+            loaded: false,
+            reason: 'probe timed out — extension file or filesystem unresponsive',
+        }), timeoutMs);
+    });
+    const probe = (async () => {
+        try {
+            const { default: lbug } = await import('@ladybugdb/core');
+            const db = new lbug.Database(':memory:');
+            // Nested finallys so `db` is closed even if the Connection ctor throws.
+            try {
+                const conn = new lbug.Connection(db);
+                try {
+                    const result = await conn.query(`LOAD EXTENSION ${extension}`);
+                    closeProbeResults(result);
+                    return { loaded: true };
+                }
+                finally {
+                    await conn.close().catch(() => { });
+                }
+            }
+            finally {
+                await db.close().catch(() => { });
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { loaded: false, reason: message.replace(/\s+/g, ' ').trim() };
+        }
+    })();
+    return await Promise.race([probe, timeout]).finally(() => clearTimeout(timer));
+}