@soulcraft/cortex 2.7.2 → 2.7.3

package/dist/hnsw/AdaptiveDiskAnnModeSelector.d.ts

@@ -0,0 +1,168 @@
+/**
+ * @module hnsw/AdaptiveDiskAnnModeSelector
+ * @description **Adaptive DiskANN** mode selector — Piece I of the
+ * cor 3.0 plan. Closes the loop on Track 2: the previous pieces
+ * built the *capability* (Piece G — Mode 1 no-PQ; Piece H — open-time
+ * madvise profile; Piece J — `/proc/meminfo` observation), and this
+ * module is the *decision* that wires those signals together into a
+ * single mode choice at build / open time.
+ *
+ * ## What this picks
+ *
+ * - **`"in-memory"`** — Mode 1. Build path: skip PQ entirely; vectors
+ *   stay RAM-resident; the walk is exact (sub-ms latency). Open
+ *   path: only valid when the on-disk header already records
+ *   `pq_m=0` — otherwise a PQ-enabled file would force the
+ *   `search_pq` path regardless of the open-time hint, so "in-memory"
+ *   open mode on a PQ file would only waste RAM on vectors the walk
+ *   doesn't read.
+ * - **`"hybrid"`** — Mode 2. PQ codes pinned in RAM via `MADV_WILLNEED`;
+ *   vectors paged on demand for rerank. The default for medium-scale
+ *   brains.
+ * - **`"on-disk"`** — Mode 3. PQ codes can page out under memory
+ *   pressure. The choice for memory-constrained or multi-tenant
+ *   deployments where many brainy+cor instances share a box.
+ *
+ * ## Algorithm
+ *
+ * Per-brain RAM budget = `0.5 × (availableBytes / max(1, activeBrains))`.
+ * The 0.5 headroom factor leaves the other half for OS slop, query
+ * intermediates, and the brain's other subsystems (metadata LSM,
+ * embeddings, etc.).
+ *
+ * 1. If the input names a Mode 1 file (`pqM === 0` from the header),
+ *    return `"in-memory"` — no other open mode is valid for a no-PQ
+ *    file.
+ * 2. At BUILD time (`pqM` undefined), try Mode 1 first: if the
+ *    vectors + graph cost fits the RAM budget AND the build cost
+ *    (`N × dim`) is below the dim-aware ceiling from
+ *    {@link mode1BuildCostCeiling}, build no-PQ. Above the ceiling,
+ *    Mode 1's `O(N · dim)` build becomes the limiting factor —
+ *    Mode 2's PQ-coded distance compute is 5-10× faster at the same
+ *    N because it replaces a `dim`-wide dot product with a
+ *    `m=16`-wide table lookup. Falling through to PQ at large N is
+ *    the right call even when vectors fit in RAM.
+ * 3. For PQ-enabled files (or build-time-too-big cases), compare the
+ *    codes-section + codebook RAM cost against the budget:
+ *    fits → `"hybrid"`; doesn't fit → `"on-disk"`.
+ * 4. If V8 heap pressure is `"critical"`, demote `"hybrid"` →
+ *    `"on-disk"` — we don't want to pile JS-heap pressure on top of
+ *    OS-RAM pressure when GC thrash will cost more than the SSD
+ *    page-in.
+ *
+ * ## Decision granularity
+ *
+ * Brain-open-time decision; not re-evaluated mid-flight. Mode
+ * switches mid-flight would require a rebuild (Mode 1 → Mode 2 means
+ * training a PQ codebook; Mode 2 → Mode 1 means evicting codes +
+ * pinning vectors), so the selector picks once and the brain runs in
+ * the chosen profile until restart. A future piece may explore
+ * triggered rebuilds when sustained pressure crosses a threshold;
+ * for now the choice is sticky.
+ */
+import { ResourceManager } from '../resource/ResourceManager.js';
+/**
+ * The three operating modes Adaptive DiskANN selects between.
+ *
+ * The strings match the vocabulary the napi surface accepts on
+ * `DiskAnnConfig.mode` (Piece G) and `NativeDiskAnn.openExisting`
+ * (Piece H), so the selector's output flows through to the Rust
+ * layer without translation.
+ */
+export type AdaptiveDiskAnnMode = 'in-memory' | 'hybrid' | 'on-disk';
+/**
+ * Per-brain statistics the selector consumes. At OPEN time these
+ * come from the file header; at BUILD time the caller supplies the
+ * expected shape (omit `pqM` to signal "build-time decision").
+ */
+export interface BrainStats {
+    /** Number of vectors. For a new build, the expected total. */
+    nodeCount: number;
+    /** Vector dimension. */
+    dim: number;
+    /** Vamana max degree (R). */
+    maxDegree: number;
+    /**
+     * PQ subspaces. `0` is the Mode 1 marker — file is already
+     * no-PQ; only `"in-memory"` is a valid open mode. Omit (or pass
+     * `undefined`) at build time so the selector can choose between
+     * Mode 1 (no PQ) and Modes 2/3 (PQ-enabled).
+     */
+    pqM?: number;
+}
+/**
+ * Resource situation at decision time. The
+ * {@link ResourceManager} is the canonical source; tests construct
+ * directly.
+ */
+export interface SystemMemoryState {
+    /**
+     * Kernel-reported `MemAvailable` (Linux) or `os.freemem()`
+     * fallback. The selector's primary RAM signal.
+     */
+    availableBytes: number;
+    /**
+     * Number of brainy instances already tracked by the
+     * ResourceManager. Divides `availableBytes` into per-brain
+     * shares.
+     */
+    activeBrains: number;
+    /**
+     * V8 heap pressure classification (same three-level shape as the
+     * system-RSS pressure). `"critical"` demotes Hybrid → OnDisk.
+     * Optional — omit if the caller doesn't observe V8 heap.
+     */
+    v8Pressure?: 'normal' | 'elevated' | 'critical';
+}
+/**
+ * Reason codes for the chosen mode. Surface for production
+ * diagnostics — a single string is enough to reconstruct the
+ * selector's reasoning from a log line.
+ */
+export type ModeSelectionReason = 'no-pq-file' | 'fits-in-memory' | 'mode1-build-too-large' | 'codes-pinned' | 'codes-paged' | 'v8-pressure-demote';
+/**
+ * Selector output. The reasoning fields make the decision
+ * diagnosable: a production log line can capture `mode`, `reason`,
+ * and `perBrainAvailable` in ~50 bytes and the operator can
+ * reconstruct exactly why the brain landed in its current profile.
+ */
+export interface ModeSelection {
+    mode: AdaptiveDiskAnnMode;
+    reason: ModeSelectionReason;
+    /** RAM cost the selector estimated for the chosen mode, in bytes. */
+    estimatedBytes: number;
+    /** Per-brain available memory used in the calculation. */
+    perBrainAvailable: number;
+}
+/**
+ * Returns the build-cost ceiling above which Mode 1 falls through to
+ * Mode 2 at this dim. See {@link MODE1_BUILD_COST_CEILING_SMALL_DIM}.
+ *
+ * Exposed for tests that need to assert the boundary calibration
+ * directly; not exported beyond the module.
+ */
+export declare function mode1BuildCostCeiling(dim: number): number;
+/**
+ * Pure selector. The wrapper code calls this with concrete inputs;
+ * tests construct {@link BrainStats} + {@link SystemMemoryState}
+ * directly to assert each branch.
+ */
+export declare function pickMode(stats: BrainStats, sys: SystemMemoryState): ModeSelection;
+/**
+ * Convenience wrapper that pulls inputs from a {@link ResourceManager}
+ * (default: the singleton) and returns the selector's choice.
+ * Production code in `NativeDiskAnnWrapper` calls this at build and
+ * open time; tests prefer {@link pickMode} directly so they can pin
+ * the system state without touching the singleton.
+ */
+export declare function selectModeFromResourceManager(stats: BrainStats, rm?: ResourceManager): ModeSelection;
+/**
+ * The mode `MappedIndex::open_with_mode(path, Auto)` would resolve to
+ * for a given header (Piece H semantics). Mirrored here so the
+ * wrapper can skip a reopen when the selector agrees with Auto —
+ * avoids opening the file twice on the cold path.
+ */
+export declare function autoModeForHeader(header: {
+    pqM: number;
+}): AdaptiveDiskAnnMode;
+//# sourceMappingURL=AdaptiveDiskAnnModeSelector.d.ts.map

package/dist/hnsw/AdaptiveDiskAnnModeSelector.js

@@ -0,0 +1,276 @@
+/**
+ * @module hnsw/AdaptiveDiskAnnModeSelector
+ * @description **Adaptive DiskANN** mode selector — Piece I of the
+ * cor 3.0 plan. Closes the loop on Track 2: the previous pieces
+ * built the *capability* (Piece G — Mode 1 no-PQ; Piece H — open-time
+ * madvise profile; Piece J — `/proc/meminfo` observation), and this
+ * module is the *decision* that wires those signals together into a
+ * single mode choice at build / open time.
+ *
+ * ## What this picks
+ *
+ * - **`"in-memory"`** — Mode 1. Build path: skip PQ entirely; vectors
+ *   stay RAM-resident; the walk is exact (sub-ms latency). Open
+ *   path: only valid when the on-disk header already records
+ *   `pq_m=0` — otherwise a PQ-enabled file would force the
+ *   `search_pq` path regardless of the open-time hint, so "in-memory"
+ *   open mode on a PQ file would only waste RAM on vectors the walk
+ *   doesn't read.
+ * - **`"hybrid"`** — Mode 2. PQ codes pinned in RAM via `MADV_WILLNEED`;
+ *   vectors paged on demand for rerank. The default for medium-scale
+ *   brains.
+ * - **`"on-disk"`** — Mode 3. PQ codes can page out under memory
+ *   pressure. The choice for memory-constrained or multi-tenant
+ *   deployments where many brainy+cor instances share a box.
+ *
+ * ## Algorithm
+ *
+ * Per-brain RAM budget = `0.5 × (availableBytes / max(1, activeBrains))`.
+ * The 0.5 headroom factor leaves the other half for OS slop, query
+ * intermediates, and the brain's other subsystems (metadata LSM,
+ * embeddings, etc.).
+ *
+ * 1. If the input names a Mode 1 file (`pqM === 0` from the header),
+ *    return `"in-memory"` — no other open mode is valid for a no-PQ
+ *    file.
+ * 2. At BUILD time (`pqM` undefined), try Mode 1 first: if the
+ *    vectors + graph cost fits the RAM budget AND the build cost
+ *    (`N × dim`) is below the dim-aware ceiling from
+ *    {@link mode1BuildCostCeiling}, build no-PQ. Above the ceiling,
+ *    Mode 1's `O(N · dim)` build becomes the limiting factor —
+ *    Mode 2's PQ-coded distance compute is 5-10× faster at the same
+ *    N because it replaces a `dim`-wide dot product with a
+ *    `m=16`-wide table lookup. Falling through to PQ at large N is
+ *    the right call even when vectors fit in RAM.
+ * 3. For PQ-enabled files (or build-time-too-big cases), compare the
+ *    codes-section + codebook RAM cost against the budget:
+ *    fits → `"hybrid"`; doesn't fit → `"on-disk"`.
+ * 4. If V8 heap pressure is `"critical"`, demote `"hybrid"` →
+ *    `"on-disk"` — we don't want to pile JS-heap pressure on top of
+ *    OS-RAM pressure when GC thrash will cost more than the SSD
+ *    page-in.
+ *
+ * ## Decision granularity
+ *
+ * Brain-open-time decision; not re-evaluated mid-flight. Mode
+ * switches mid-flight would require a rebuild (Mode 1 → Mode 2 means
+ * training a PQ codebook; Mode 2 → Mode 1 means evicting codes +
+ * pinning vectors), so the selector picks once and the brain runs in
+ * the chosen profile until restart. A future piece may explore
+ * triggered rebuilds when sustained pressure crosses a threshold;
+ * for now the choice is sticky.
+ */
+import { ResourceManager, } from '../resource/ResourceManager.js';
+/**
+ * Fraction of per-brain available memory the chosen mode's working
+ * set must fit within. Half the available; the other half is for OS
+ * slop, query intermediates, and the brain's other subsystems
+ * (metadata LSM, embeddings, page-cache headroom).
+ */
+const HEADROOM_FACTOR = 0.5;
+/**
+ * Default PQ subspace count for BUILD-time cost estimation. Matches
+ * the {@link NativeDiskAnnWrapper} default. Used only when the
+ * caller hasn't pinned `pqM` themselves — an existing file's header
+ * always provides the real value.
+ */
+const DEFAULT_PQ_M_FOR_ESTIMATE = 16;
+/**
+ * Default codebook ksub (centroids per subspace) — 256 is the
+ * 8-bit-code published default the build path uses (Piece 13).
+ */
+const DEFAULT_KSUB = 256;
+/**
+ * Maximum `N × dim` above which Mode 1's `O(N · dim)` build cost
+ * dominates the selector decision. Even when the vectors + graph fit
+ * in RAM, the build time becomes the limiting factor at this scale —
+ * Mode 2's PQ-coded distance compute is 5-10× faster (16-byte code
+ * lookup vs `dim`-wide dot product) so a brain that builds in ~50
+ * minutes under Mode 1 builds in ~5-10 minutes under Mode 2 at the
+ * cost of ~3× query latency (sub-ms → ~3 ms p50).
+ *
+ * The ceiling is **dim-aware** because per-cost-unit wall-clock varies
+ * significantly with dim — SIMD width, cache footprint, and vectorised
+ * distance compute all favour smaller dims by roughly an order of
+ * magnitude per cost-unit. A single dim-blind ceiling miscalibrates
+ * one regime or the other.
+ *
+ * Anchor measurements (bxl9000, 32-core Zen 4, AVX-512 dispatched
+ * kernel from `e6d3756`):
+ *
+ * | Workload | N×dim | Build (Mode 1) | μs/cost-unit |
+ * |---|---:|---:|---:|
+ * | SIFT1M     (dim=128) | 128M     | 83 s    | 0.65 |
+ * | SIFT10M    (dim=128) | 1.28B    | 20 min  | 0.93 |
+ * | 1M × 384            | 384M     | 17 min  | 2.65 |
+ * | 1M × 384 (pre-SIMD) | 384M     | 47 min  | 7.33 |
+ *
+ * Result files: `docs/verification/result-sift1m-auto.json`,
+ * `result-sift10m-in-memory.json`, `result-1m-avx512.json`,
+ * `result-1m-auto.json`.
+ *
+ * Target wall-clock budget: ≤ 24 min (the "acceptable one-time build"
+ * boundary). At dim ≤ 256 the per-cost-unit time stays under ~1 μs,
+ * so 2 B cost-units ≈ 33 min worst case, safe with super-linear
+ * scaling headroom. At dim > 256 the per-cost-unit time climbs into
+ * the 2-7 μs range, capping the budget near 400 M cost-units.
+ *
+ * This is a single internal constant set, not a user-facing knob.
+ * Power users who need a specific mode override the entire selector
+ * via `DiskAnnConfig.mode = "in-memory" | "hybrid" | "on-disk"`, the
+ * existing escape hatch.
+ */
+const MODE1_BUILD_COST_CEILING_SMALL_DIM = 2_000_000_000;
+const MODE1_BUILD_COST_CEILING_LARGE_DIM = 400_000_000;
+const MODE1_DIM_BOUNDARY = 256;
+/**
+ * Returns the build-cost ceiling above which Mode 1 falls through to
+ * Mode 2 at this dim. See {@link MODE1_BUILD_COST_CEILING_SMALL_DIM}.
+ *
+ * Exposed for tests that need to assert the boundary calibration
+ * directly; not exported beyond the module.
+ */
+export function mode1BuildCostCeiling(dim) {
+    return dim <= MODE1_DIM_BOUNDARY
+        ? MODE1_BUILD_COST_CEILING_SMALL_DIM
+        : MODE1_BUILD_COST_CEILING_LARGE_DIM;
+}
+/**
+ * Pure selector. The wrapper code calls this with concrete inputs;
+ * tests construct {@link BrainStats} + {@link SystemMemoryState}
+ * directly to assert each branch.
+ */
+export function pickMode(stats, sys) {
+    const perBrainAvailable = sys.availableBytes / Math.max(1, sys.activeBrains);
+    const budget = HEADROOM_FACTOR * perBrainAvailable;
+    // Case A: file is already Mode 1 (pqM === 0 in header). Only
+    // "in-memory" is algorithmically valid — codes don't exist.
+    if (stats.pqM === 0) {
+        return {
+            mode: 'in-memory',
+            reason: 'no-pq-file',
+            estimatedBytes: estimateMode1Bytes(stats),
+            perBrainAvailable,
+        };
+    }
+    // Case B: BUILD-time decision (pqM undefined). Try Mode 1 first
+    // if BOTH the RAM cost fits the budget AND the build cost (N × dim)
+    // is below the dim-aware ceiling. The second guard catches the
+    // "vectors fit in RAM but the build would take 47 minutes" case —
+    // above the ceiling, Mode 2's PQ-coded build is ~5-10× faster at
+    // small recall cost, so the selector prefers it even though Mode 1
+    // would theoretically work.
+    if (stats.pqM === undefined) {
+        const mode1Cost = estimateMode1Bytes(stats);
+        const buildCost = stats.nodeCount * stats.dim;
+        const buildCostCeiling = mode1BuildCostCeiling(stats.dim);
+        if (mode1Cost <= budget && buildCost <= buildCostCeiling) {
+            return {
+                mode: 'in-memory',
+                reason: 'fits-in-memory',
+                estimatedBytes: mode1Cost,
+                perBrainAvailable,
+            };
+        }
+        // Mode 1 was RAM-feasible but build-cost-prohibitive: route to
+        // Mode 2 (hybrid) with the distinct `mode1-build-too-large`
+        // reason so production logs can tell this fall-through apart
+        // from the RAM-driven fall-through (Case C below). Codes are
+        // ~m bytes/node, vectors are ~dim×4 bytes/node, so codes are
+        // strictly smaller than vectors at any dim ≥ 4 — if mode1Cost
+        // fit the budget, codesCost will too. Guaranteed hybrid (no
+        // on-disk branch needed here).
+        if (mode1Cost <= budget && buildCost > buildCostCeiling) {
+            const codesCost = estimateCodesBytes(stats, DEFAULT_PQ_M_FOR_ESTIMATE);
+            // V8-critical demote applies here too — same defensive rule
+            // as Case C below.
+            if (sys.v8Pressure === 'critical') {
+                return {
+                    mode: 'on-disk',
+                    reason: 'v8-pressure-demote',
+                    estimatedBytes: codesCost,
+                    perBrainAvailable,
+                };
+            }
+            return {
+                mode: 'hybrid',
+                reason: 'mode1-build-too-large',
+                estimatedBytes: codesCost,
+                perBrainAvailable,
+            };
+        }
+    }
+    // Case C: PQ-enabled file (pqM > 0) OR build-time too big for
+    // Mode 1. Choose between Hybrid (codes pinned) and OnDisk (codes
+    // can page) based on whether the codes section fits the budget.
+    const m = stats.pqM ?? DEFAULT_PQ_M_FOR_ESTIMATE;
+    const codesCost = estimateCodesBytes(stats, m);
+    let mode;
+    let reason;
+    if (codesCost <= budget) {
+        mode = 'hybrid';
+        reason = 'codes-pinned';
+    }
+    else {
+        mode = 'on-disk';
+        reason = 'codes-paged';
+    }
+    // Defensive demote: if V8 heap is critical, don't pile JS-heap
+    // pressure on top of OS-RAM pressure. Drop Hybrid → OnDisk so the
+    // OS page cache stays in charge of codes residency.
+    if (mode === 'hybrid' && sys.v8Pressure === 'critical') {
+        mode = 'on-disk';
+        reason = 'v8-pressure-demote';
+    }
+    return {
+        mode,
+        reason,
+        estimatedBytes: codesCost,
+        perBrainAvailable,
+    };
+}
+/**
+ * Mode 1 RAM commitment. The on-disk file's codebook + codes
+ * sections are zero bytes in Mode 1; only the graph + vectors
+ * sections cost RAM if we pre-page them.
+ */
+function estimateMode1Bytes(stats) {
+    return stats.nodeCount * (stats.dim + stats.maxDegree) * 4;
+}
+/**
+ * Codes-section + codebook RAM commitment for Modes 2/3. Codes
+ * dominate at scale (n × m bytes); codebook is constant per
+ * dimension (m × ksub × dsub × 4 = ksub × dim × 4 = ~1 MB at the
+ * default ksub=256).
+ */
+function estimateCodesBytes(stats, m) {
+    const codesBytes = stats.nodeCount * m;
+    const codebookBytes = DEFAULT_KSUB * stats.dim * 4;
+    return codesBytes + codebookBytes;
+}
+/**
+ * Convenience wrapper that pulls inputs from a {@link ResourceManager}
+ * (default: the singleton) and returns the selector's choice.
+ * Production code in `NativeDiskAnnWrapper` calls this at build and
+ * open time; tests prefer {@link pickMode} directly so they can pin
+ * the system state without touching the singleton.
+ */
+export function selectModeFromResourceManager(stats, rm = ResourceManager.getInstance()) {
+    const osMemory = rm.getOsMemorySnapshot();
+    const profile = rm.getResourceProfile();
+    return pickMode(stats, {
+        availableBytes: osMemory.availableBytes,
+        activeBrains: profile.activeInstances,
+        v8Pressure: profile.v8Heap.pressure,
+    });
+}
+/**
+ * The mode `MappedIndex::open_with_mode(path, Auto)` would resolve to
+ * for a given header (Piece H semantics). Mirrored here so the
+ * wrapper can skip a reopen when the selector agrees with Auto —
+ * avoids opening the file twice on the cold path.
+ */
+export function autoModeForHeader(header) {
+    return header.pqM === 0 ? 'in-memory' : 'hybrid';
+}
+//# sourceMappingURL=AdaptiveDiskAnnModeSelector.js.map