@soulcraft/cortex 2.7.2 → 2.7.3

package/dist/hnsw/NativeDiskAnnWrapper.js

@@ -0,0 +1,738 @@
+/**
+ * @module hnsw/NativeDiskAnnWrapper
+ * @description TypeScript wrapper around cor's native **Adaptive
+ * DiskANN** engine. Satisfies brainy 8.0's `VectorIndexProvider`
+ * contract (see [`providerContracts.ts`](../providerContracts.ts))
+ * so brainy treats it as the standard vector index slot —
+ * `addItem` / `search` / `rebuild` / `flush` / ... Underneath,
+ * every operation routes through cor's pure-Rust DiskANN engine
+ * (`native/diskann/`).
+ *
+ * @example
+ * ```typescript
+ * import { Brainy } from '@soulcraft/brainy'
+ *
+ * // Cor is auto-detected by brainy's plugin system on init.
+ * const brain = new Brainy({
+ *   storage: { type: 'filesystem', rootDirectory: '/data/idx' }
+ * })
+ * await brain.init()  // [cor] Adaptive DiskANN engaged (mode auto)
+ *
+ * await brain.add({ data: 'native rust acceleration', type: 'concept' })
+ * const hits = await brain.search('billion scale ann', 10)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Default zero-config — the adaptive selector picks Mode 1 / 2 / 3
+ * // from observed memory pressure. Most users only set `recall`.
+ * const brain = new Brainy({
+ *   storage: { type: 'filesystem', rootDirectory: '/data/idx' },
+ *   vector: {
+ *     recall: 'balanced',  // 'fast' | 'balanced' | 'accurate'
+ *   }
+ * })
+ * ```
+ *
+ * ## Operating model
+ *
+ * Adaptive DiskANN is build-once, query-many: the on-disk file
+ * embeds the Vamana graph plus — depending on the build mode — an
+ * optional PQ codebook + codes section + the full vectors, all in
+ * a single contiguous mmap-able layout (see `native/diskann/src/format.rs`).
+ * Dynamic insertions go to a small in-memory **delta buffer** that
+ * brute-force-searches alongside the main index until the next
+ * `rebuild()` folds them in. This matches FreshDiskANN's published
+ * online-update model.
+ *
+ * The wrapper picks an operating mode (in-memory / hybrid /
+ * on-disk) at build time and open time via the
+ * {@link AdaptiveDiskAnnModeSelector}; see that module for the
+ * decision tree. Operators set nothing — observed memory drives
+ * the choice.
+ *
+ * ## Search path
+ *
+ * 1. Query the main index via the native DiskANN searcher:
+ *    - **Mode 1**: exact-distance walk over full vectors (no PQ,
+ *      no rerank — the walk's top-L is the exact top-L).
+ *    - **Mode 2/3**: PQ-greedy walk in RAM (codes pinned or paged
+ *      depending on mode), full-vector re-rank on the top
+ *      `k × paddingFactor` candidates.
+ * 2. Brute-force the delta buffer (typically <0.1% of total
+ *    size after a recent rebuild).
+ * 3. Merge + sort + truncate to `k`.
+ *
+ * ## When this wrapper engages
+ *
+ * The cor plugin (`src/plugin.ts`) registers this wrapper under
+ * brainy 8.0's canonical `'vector'` provider key. Whenever cor is
+ * installed, brainy's vector index slot resolves to Adaptive DiskANN.
+ */
+import { loadNativeModule } from '../native/index.js';
+import { prodLog } from '@soulcraft/brainy/internals';
+import { mkdirSync, writeFileSync, renameSync, existsSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { autoModeForHeader, selectModeFromResourceManager, } from './AdaptiveDiskAnnModeSelector.js';
+/**
+ * Node-count threshold above which `useMmapAdjacency: 'auto'`
+ * resolves to file-backed. Below this, the in-RAM build adjacency
+ * fits comfortably in heap; above, the per-row mutex table starts
+ * to dominate. 100 M matches the published DiskANN guidance and
+ * the comment that lives next to `AdjacencyBackend::Mmap` in the
+ * Rust crate.
+ */
+const MMAP_ADJACENCY_AUTO_THRESHOLD = 100_000_000;
+/**
+ * **Canonical .dkann path convention** (brainy 8.0 + cor 3.0
+ * lockstep). When `DiskAnnIndexConfig.indexPath` is omitted, the
+ * wrapper derives the path by passing this key to the storage
+ * adapter's `getBinaryBlobPath`. Living under `_system/` puts
+ * the DiskANN file inside brainy's existing backup-by-default
+ * tree — no special inclusion rule needed in `db.persist` /
+ * `gsutil` / `rclone` configurations.
+ *
+ * Sharded deployments override `indexPath` explicitly with per-
+ * shard suffixes (e.g. `_system/vector-index/shard-7.dkann`).
+ */
+const DEFAULT_INDEX_PATH_KEY = '_system/vector-index/main.dkann';
+/**
+ * Derive the canonical `.dkann` path from a storage adapter, or
+ * return `null` if the adapter doesn't expose `getBinaryBlobPath`
+ * (cloud adapters that don't support binary blobs, or no adapter
+ * supplied). The caller decides whether `null` is a hard error or
+ * a graceful fallback.
+ */
+function deriveIndexPath(storage) {
+    if (!storage)
+        return null;
+    const getBinaryBlobPath = storage.getBinaryBlobPath;
+    if (typeof getBinaryBlobPath !== 'function')
+        return null;
+    const path = getBinaryBlobPath.call(storage, DEFAULT_INDEX_PATH_KEY);
+    return typeof path === 'string' && path.length > 0 ? path : null;
+}
+/**
+ * **Recall presets** (brainy 8.0 lockstep). One knob (`recall`)
+ * maps to the search-time `defaultLSearch` + `defaultPaddingFactor`
+ * pair. The `'balanced'` preset reproduces brainy 7.x's defaults so
+ * existing brains don't experience a recall shift on upgrade.
+ *
+ * Brainy 8.0's JS HNSW path exposes the same preset names with
+ * algorithm-appropriate values (`{m, efConstruction, efSearch}`
+ * tuples); see `brainy/.strategy/COR-3.0-INTEGRATION.md`.
+ */
+const RECALL_PRESETS = {
+    fast: { defaultLSearch: 50, defaultPaddingFactor: 1.0 },
+    balanced: { defaultLSearch: 100, defaultPaddingFactor: 1.2 },
+    accurate: { defaultLSearch: 200, defaultPaddingFactor: 1.5 },
+};
+const DEFAULTS = {
+    pqM: 16,
+    pqKsub: 256,
+    maxDegree: 64,
+    searchListSize: 100,
+    alpha: 1.2,
+    defaultLSearch: 100,
+    defaultPaddingFactor: 1.2,
+    useMmapAdjacency: 'auto',
+    mode: 'auto',
+};
+/**
+ * Predicate-pushdown thresholds (#10). When `find()` supplies a
+ * metadata∩graph `allowedIds` universe, the wrapper pushes it INTO the native
+ * beam walk instead of post-filtering — but only when the predicate is
+ * selective enough that post-filtering would lose recall. At or below
+ * `PUSHDOWN_MAX_SELECTIVITY` (allowed/total) the unfiltered top-(k×2) rarely
+ * holds k allowed hits, so pushdown wins; above it, post-filtering already
+ * keeps plenty and is cheaper (no slot translation of a huge set).
+ * `PUSHDOWN_MAX_LSEARCH` is the walk↔brute-force crossover: when the walk
+ * width the selectivity demands (~k/selectivity) would exceed it, the walk
+ * is BOTH slow (the bounded candidate list is O(L) per insert) and low-recall
+ * (allowed points sit outside the frontier), so pushdown switches to an exact
+ * scan of the allowed set instead. Below it, the walk runs at its natural,
+ * never-capped width. Zero-config: both are derived defaults, not user knobs.
+ */
+const PUSHDOWN_MAX_SELECTIVITY = 0.1;
+const PUSHDOWN_MAX_LSEARCH = 4096;
+/**
+ * Allowed-set size at or below which pushdown exact-scans the set rather than
+ * graph-walking it. Measured crossover (SIFT/128-d on the reference host): an
+ * exact scan of ≤ ~32k vectors (≈4M float ops, low single-digit ms) is both
+ * faster than the filtered walk's floor AND exact (recall 1.0), because the
+ * walk carries fixed traversal + re-rank overhead and its bounded candidate
+ * list is O(L) per insert. Above this the walk is the fast-approximate path
+ * for large allowed sets at higher selectivity. Zero-config default; a future
+ * O(log L) candidate list would raise the walk's competitiveness and shift
+ * this crossover up.
+ *
+ * Measured (SIFT 1M, 128-d, bxl9000): exact scan of 65,536 vectors ≈ 4–6 ms
+ * and recall 1.0; at that count the filtered walk is ~equal latency but only
+ * ~0.73 recall, so the exact scan is the better pick. Past ~65k the scan
+ * dominates query time and the walk (small L at the implied higher
+ * selectivity) wins — e.g. 5% of a 10M index (500k) correctly routes to it.
+ */
+const PUSHDOWN_BRUTE_MAX_ALLOWED = 65536;
+export class NativeDiskAnnWrapper {
+    config;
+    distanceFunction;
+    storage;
+    persistMode;
+    /** Live searcher instance — null until the first build. */
+    native = null;
+    /** Newly added entries since the last build. Brute-force searched. */
+    delta = new Map();
+    /** Removed entries — filtered out at search time. */
+    tombstones = new Set();
+    /** Bidirectional UUID ↔ slot map for the main index. */
+    slotByUuid = new Map();
+    uuidBySlot = new Map();
+    /**
+     * **Piece I — Adaptive DiskANN.** The selector's most recent
+     * decision, exposed via {@link getLastModeSelection} for telemetry
+     * and tests. `null` until the first build or open.
+     */
+    lastSelection = null;
+    constructor(config, distanceFunction, options = {}) {
+        // Merge order matters:
+        //   1. DEFAULTS      — baseline (matches the 'balanced' preset).
+        //   2. recall preset — overrides DEFAULTS for the chosen tier
+        //                      WHEN the user supplied `recall`.
+        //   3. config        — user overrides win over both. So
+        //                      `recall: 'fast', defaultLSearch: 200`
+        //                      gives lSearch=200, not the fast preset's
+        //                      50.
+        const preset = config.recall ? RECALL_PRESETS[config.recall] : {};
+        const merged = { ...DEFAULTS, ...preset, ...config };
+        // Path resolution: explicit `indexPath` wins; otherwise derive
+        // from the storage adapter using the canonical convention
+        // (`_system/vector-index/main.dkann`). If neither is available
+        // the constructor throws — without a path, the wrapper has no
+        // anchor for build, open, or rebuild.
+        const resolvedIndexPath = merged.indexPath ?? deriveIndexPath(options.storage);
+        if (!resolvedIndexPath) {
+            throw new Error('NativeDiskAnnWrapper: indexPath is required when no ' +
+                'storage adapter (with getBinaryBlobPath) is provided. ' +
+                'Pass `indexPath` explicitly or supply a filesystem-backed ' +
+                'storage in `options.storage` so the wrapper can derive ' +
+                `the canonical path \`{root}/${DEFAULT_INDEX_PATH_KEY}\`.`);
+        }
+        this.config = { ...merged, indexPath: resolvedIndexPath };
+        this.distanceFunction = distanceFunction;
+        this.storage = options.storage ?? null;
+        this.persistMode = options.persistMode ?? 'immediate';
+        // Try to open an existing file. If absent, the index stays
+        // empty until the first rebuild() flushes the delta buffer.
+        this.tryOpenExisting();
+    }
+    /**
+     * Append an entry to the delta buffer. Persisted by the next
+     * `rebuild()` call, which folds the delta into the main index.
+     */
+    async addItem(item) {
+        if (this.tombstones.has(item.id)) {
+            this.tombstones.delete(item.id);
+        }
+        this.delta.set(item.id, item.vector);
+        return item.id;
+    }
+    /**
+     * Mark an entry as removed. Filtered out at search time; physically
+     * removed at the next `rebuild()`.
+     */
+    async removeItem(id) {
+        const inDelta = this.delta.delete(id);
+        const inMain = this.slotByUuid.has(id);
+        if (inMain)
+            this.tombstones.add(id);
+        return inDelta || inMain;
+    }
+    async search(queryVector, k = 10, filter, options) {
+        // Predicate pushdown: a SELECTIVE metadata∩graph universe is evaluated
+        // INSIDE the native walk rather than dropped afterwards.
+        const allowedIds = options?.allowedIds;
+        if (allowedIds && this.native && allowedIds.size > 0) {
+            const mainSize = this.native.size();
+            const selectivity = mainSize > 0 ? allowedIds.size / mainSize : 1;
+            if (selectivity <= PUSHDOWN_MAX_SELECTIVITY) {
+                return this.searchPushdown(queryVector, k, allowedIds, filter, options);
+            }
+            // Not selective enough to push down — fold allowedIds into the
+            // post-filter predicate so the result semantics are identical.
+            const inner = filter;
+            filter = async (id) => {
+                if (!allowedIds.has(id))
+                    return false;
+                return inner ? inner(id) : true;
+            };
+        }
+        const lSearch = Math.max(this.config.defaultLSearch, k * 2);
+        const padding = options?.rerank?.multiplier ?? this.config.defaultPaddingFactor;
+        // 1. Main-index PQ-greedy walk (returns slot ids).
+        const mainHits = this.native
+            ? this.native.search(Array.from(queryVector), k * 2, // over-fetch so filter / tombstone losses don't starve final result
+            lSearch, padding)
+            : [];
+        // 2. Hydrate slot → uuid; drop tombstoned + filter-rejected.
+        const merged = [];
+        for (const hit of mainHits) {
+            const uuid = this.uuidBySlot.get(hit.slot);
+            if (!uuid)
+                continue;
+            if (this.tombstones.has(uuid))
+                continue;
+            if (filter && !(await filter(uuid)))
+                continue;
+            merged.push([uuid, hit.distance]);
+        }
+        // 3. Brute-force the delta buffer.
+        for (const [id, v] of this.delta) {
+            if (filter && !(await filter(id)))
+                continue;
+            const d = this.distanceFunction(queryVector, v);
+            merged.push([id, d]);
+        }
+        // 4. Sort ascending by distance, truncate to k.
+        merged.sort((a, b) => a[1] - b[1]);
+        return merged.slice(0, k);
+    }
+    /**
+     * Predicate-pushdown search (#10). Translates the metadata∩graph entity
+     * universe to main-index slots, pushes them into the native beam walk
+     * (which traverses *through* all nodes but only collects allowed slots),
+     * and inflates `l_search` by ~1/selectivity so a selective predicate still
+     * surfaces k allowed neighbours. Delta-buffer entries (no slot yet) are
+     * brute-forced. This is the high-recall path for selective filtered
+     * `find()` — post-filtering the unfiltered top-k loses recall when few of
+     * those candidates pass the predicate.
+     *
+     * @param queryVector - The query embedding.
+     * @param k - Number of nearest allowed neighbours to return.
+     * @param allowedIds - Entity UUIDs permitted in the result (the find() universe).
+     * @param filter - Optional additional async predicate, composed with allowedIds.
+     * @param options - Optional rerank multiplier override.
+     * @returns Up to k `[uuid, distance]` pairs, ascending by distance.
+     */
+    async searchPushdown(queryVector, k, allowedIds, filter, options) {
+        const padding = options?.rerank?.multiplier ?? this.config.defaultPaddingFactor;
+        const merged = [];
+        // 1. Native filtered walk over the main index (allowed slots only).
+        if (this.native) {
+            const allowedSlots = [];
+            for (const id of allowedIds) {
+                const slot = this.slotByUuid.get(id);
+                if (slot !== undefined)
+                    allowedSlots.push(slot);
+            }
+            if (allowedSlots.length > 0) {
+                const mainSize = this.native.size();
+                const selectivity = allowedSlots.length / Math.max(1, mainSize);
+                // Over-fetch so tombstone + extra-filter losses don't starve k.
+                const nativeK = Math.min(allowedSlots.length, Math.max(k * 2, k));
+                // Walk width needed to surface k allowed neighbours (~k/selectivity).
+                const idealL = Math.ceil((k / Math.max(selectivity, 1e-9)) * 1.5);
+                // Exact-scan when the allowed set is small enough to scan cheaply, OR
+                // when the walk would be capped (extreme selectivity). Both regimes:
+                // brute is faster than the walk AND exact (recall 1.0). The walk only
+                // wins for large allowed sets at higher selectivity, where its L stays
+                // small. (Measured on SIFT: brute beats the walk up to ~32k allowed.)
+                const useBrute = allowedSlots.length <= PUSHDOWN_BRUTE_MAX_ALLOWED || idealL > PUSHDOWN_MAX_LSEARCH;
+                let hits;
+                if (useBrute) {
+                    // Exact scan of the allowed set: recall 1.0, O(|allowed|·dim).
+                    hits = this.native.searchExactSlots(Array.from(queryVector), nativeK, allowedSlots);
+                }
+                else {
+                    // Medium selectivity: filtered graph walk with selectivity-tuned L
+                    // (never capped here, so the bounded candidate list stays cheap).
+                    const lSearch = Math.max(this.config.defaultLSearch, k * 2, idealL);
+                    hits = this.native.searchFiltered(Array.from(queryVector), nativeK, allowedSlots, lSearch, padding);
+                }
+                for (const hit of hits) {
+                    const uuid = this.uuidBySlot.get(hit.slot);
+                    if (!uuid)
+                        continue;
+                    if (this.tombstones.has(uuid))
+                        continue;
+                    if (filter && !(await filter(uuid)))
+                        continue;
+                    merged.push([uuid, hit.distance]);
+                }
+            }
+        }
+        // 2. Brute-force the delta buffer (allowed entries only).
+        for (const [id, v] of this.delta) {
+            if (!allowedIds.has(id))
+                continue;
+            if (filter && !(await filter(id)))
+                continue;
+            const d = this.distanceFunction(queryVector, v);
+            merged.push([id, d]);
+        }
+        // 3. Sort ascending by distance, truncate to k.
+        merged.sort((a, b) => a[1] - b[1]);
+        return merged.slice(0, k);
+    }
+    size() {
+        const mainSize = this.native ? this.native.size() : 0;
+        return (mainSize +
+            this.delta.size -
+            // Tombstones from the main index reduce effective size.
+            this.countMainTombstones());
+    }
+    clear() {
+        this.delta.clear();
+        this.tombstones.clear();
+        this.slotByUuid.clear();
+        this.uuidBySlot.clear();
+        this.native = null;
+    }
+    /**
+     * Rebuild the main index from scratch: concatenate (current main −
+     * tombstones) ∪ delta, run a full DiskANN build, swap the searcher
+     * atomically.
+     *
+     * At billion-scale this is the expensive operation (hours of build
+     * time). Operators schedule it during off-peak; the delta buffer
+     * absorbs writes in between.
+     *
+     * The optional `recall` argument overrides the wrapper's
+     * construction-time recall preset for this rebuild only — useful
+     * when an operator wants to ship a higher-quality index after a
+     * data-quality push but kept the brain on `'balanced'` originally.
+     * Omit to keep the wrapper's current preset.
+     */
+    async rebuild(options) {
+        const bindings = loadNativeModule();
+        // napi-rs exports the class as `NativeDiskAnn` (PascalCase
+        // normalization of the Rust ident `NativeDiskANN`). The TS type
+        // alias `NativeDiskANN = NativeDiskAnn` in `native/index.d.ts` is
+        // for backwards-compat in *types* only — at runtime there's a
+        // single export under the napi-normalized name.
+        const NativeDiskANN = bindings.NativeDiskAnn;
+        if (!NativeDiskANN) {
+            throw new Error('NativeDiskANN binding missing — rebuild requires the cor native module');
+        }
+        // Build the new logical slot ordering: (live old slots) + (delta).
+        // **Critical for billion-scale correctness**: the old vectors stay
+        // mmap'd inside the native module — we only pass slot IDs across
+        // the FFI boundary, not the vector data itself. At 1B × 1536 × 4
+        // bytes = ~6 TB this is the difference between "rebuild works" and
+        // "rebuild OOMs."
+        const liveOldSlots = [];
+        const newUuids = [];
+        if (this.native) {
+            // Iterate in slot order so the new index's first n_live slots
+            // mirror the OLD index's surviving subset in deterministic order.
+            // We deliberately iterate by sorted slot id rather than uuidBySlot
+            // insertion order — sorting keeps the Vamana entry point stable
+            // and the on-disk vector section's locality similar to the
+            // pre-rebuild file (less page-cache turnover during the post-
+            // rebuild warm-up).
+            const sortedSlots = Array.from(this.uuidBySlot.keys()).sort((a, b) => a - b);
+            for (const slot of sortedSlots) {
+                const uuid = this.uuidBySlot.get(slot);
+                if (this.tombstones.has(uuid))
+                    continue;
+                liveOldSlots.push(slot);
+                newUuids.push(uuid);
+            }
+        }
+        const dim = this.config.dimensions;
+        const deltaCount = this.delta.size;
+        let deltaBuf = null;
+        if (deltaCount > 0) {
+            deltaBuf = new Float32Array(deltaCount * dim);
+            let idx = 0;
+            for (const [uuid, vector] of this.delta) {
+                if (vector.length !== dim) {
+                    throw new Error(`NativeDiskAnnWrapper.rebuild: vector dim ${vector.length} ≠ index dim ${dim}`);
+                }
+                deltaBuf.set(vector, idx * dim);
+                newUuids.push(uuid);
+                idx++;
+            }
+        }
+        if (liveOldSlots.length + deltaCount === 0) {
+            prodLog?.warn?.('NativeDiskAnnWrapper.rebuild: nothing to build');
+            return;
+        }
+        const totalCount = liveOldSlots.length + deltaCount;
+        // Apply optional recall override for this rebuild only.
+        if (options?.recall) {
+            const preset = RECALL_PRESETS[options.recall];
+            this.config = { ...this.config, ...preset };
+        }
+        // **Adaptive DiskANN mode selection (Piece I)** — pick the
+        // build-time mode based on observed memory unless the caller
+        // has explicitly pinned it on the config. The selector
+        // chooses "in-memory" for brains that fit in RAM (no PQ,
+        // sub-ms search), "hybrid" for medium scale, "on-disk" when
+        // memory is tight or many brains share the box.
+        const maxDegree = this.config.maxDegree;
+        const buildMode = this.resolveBuildMode({
+            nodeCount: totalCount,
+            dim,
+            maxDegree,
+        });
+        this.lastSelection = buildMode.selection;
+        const cfg = {
+            mode: buildMode.mode,
+            vamana: {
+                maxDegree,
+                searchListSize: this.config.searchListSize,
+                alpha: this.config.alpha,
+                seed: BigInt(0xd15ca4440ffff00dn),
+                parallel: true,
+                parallelBatch: 64,
+            },
+            // pq config is read only when mode is "hybrid" or "on-disk";
+            // the napi surface ignores it for "in-memory". The wrapper's
+            // internal DEFAULTS supply pqM / pqKsub for the PQ modes.
+            pq: {
+                m: this.config.pqM,
+                ksub: this.config.pqKsub,
+                iterations: 25,
+                trainingSample: Math.min(200_000, totalCount),
+            },
+            adjacency: this.resolveAdjacencyBackend(totalCount),
+        };
+        // Ensure the .dkann's parent dir exists — the native build writes straight
+        // to outputPath and won't create intermediate dirs (e.g. _system/vector-index).
+        mkdirSync(dirname(this.config.indexPath), { recursive: true });
+        const newNative = NativeDiskANN.rebuildFromExisting({
+            existingPath: this.native ? this.config.indexPath : undefined,
+            liveOldSlots,
+            deltaVectors: deltaBuf != null
+                ? Buffer.from(deltaBuf.buffer, deltaBuf.byteOffset, deltaBuf.byteLength)
+                : undefined,
+            deltaCount,
+            dim,
+            outputPath: this.config.indexPath,
+            cfg,
+        });
+        // Rebuild the bidirectional UUID↔slot maps from `newUuids`. New
+        // slot `i` corresponds to `newUuids[i]` — this matches the napi
+        // layout invariant (live old slots first, delta tail second).
+        const newSlotByUuid = new Map();
+        const newUuidBySlot = new Map();
+        for (let i = 0; i < newUuids.length; i++) {
+            newSlotByUuid.set(newUuids[i], i);
+            newUuidBySlot.set(i, newUuids[i]);
+        }
+        // Atomic swap.
+        this.native = newNative;
+        this.slotByUuid = newSlotByUuid;
+        this.uuidBySlot = newUuidBySlot;
+        this.delta.clear();
+        this.tombstones.clear();
+        // Persist the slot map (slot i → uuid) next to the .dkann so a cold restart
+        // can rehydrate it (tryOpenExisting/loadSlots). Without this the reopened
+        // index can't map results to entity IDs → vector search returns empty.
+        this.persistSlots(newUuids);
+    }
+    /**
+     * Flush the delta buffer to disk. For DiskANN the delta is in-memory
+     * by design (a few MB at most between rebuilds); returns the buffer
+     * size for parity with HNSW's flush contract.
+     */
+    async flush() {
+        return this.delta.size;
+    }
+    getPersistMode() {
+        return this.persistMode;
+    }
+    tryOpenExisting() {
+        try {
+            const bindings = loadNativeModule();
+            // napi-rs exports the class as `NativeDiskAnn` (PascalCase
+            // normalization of the Rust ident `NativeDiskANN`). The TS
+            // type alias `NativeDiskANN = NativeDiskAnn` in
+            // `native/index.d.ts` is for backwards-compat in *types*
+            // only — at runtime there's a single export under the
+            // napi-normalized name.
+            const NativeDiskANN = bindings.NativeDiskAnn;
+            if (!NativeDiskANN)
+                return;
+            // **Adaptive DiskANN open-mode selection (Piece I).** Open
+            // with Auto first to read the header; the selector then
+            // decides whether the file should be reopened with a
+            // different mode. Common case (Auto's resolution matches the
+            // selector's pick) is a single open; only mismatches pay the
+            // reopen cost.
+            let native = NativeDiskANN.openExisting(this.config.indexPath);
+            const header = native.header();
+            const stats = {
+                nodeCount: header.nodeCount,
+                dim: header.dim,
+                maxDegree: header.maxDegree,
+                pqM: header.pqM,
+            };
+            const selection = this.resolveOpenMode(stats);
+            this.lastSelection = selection.selection;
+            const autoMode = autoModeForHeader({ pqM: header.pqM });
+            if (selection.mode !== autoMode) {
+                native = NativeDiskANN.openExisting(this.config.indexPath, selection.mode);
+            }
+            this.native = native;
+            // Rehydrate the persisted slot map (slot i → uuid) that rebuild() writes
+            // next to the .dkann. The native index stores vectors by slot only, so
+            // without this map search() can't map hits back to entity IDs (returns
+            // empty on a cold restart) and rebuild() would enumerate zero existing
+            // entries and drop the persisted index. If the map is missing/corrupt the
+            // loaded index is unusable on its own — discard it so the next rebuild()
+            // regenerates both consistently.
+            if (!this.loadSlots()) {
+                this.native = null;
+            }
+        }
+        catch {
+            // No existing file — index stays empty until first rebuild().
+            this.native = null;
+        }
+    }
+    /** Sibling path for the persisted slot map, next to the `.dkann`. */
+    slotsPath() {
+        return this.config.indexPath.replace(/\.dkann$/, '.slots.json');
+    }
+    /**
+     * Persist the slot map (slot i → `uuids[i]`) next to the `.dkann` so a cold
+     * restart can rehydrate it (see {@link tryOpenExisting}). Atomic tmp+rename.
+     * Lives under the same `_system/` tree as the index, so it travels with
+     * `db.persist` and bypasses branch scoping just like the `.dkann`.
+     */
+    persistSlots(uuids) {
+        try {
+            const p = this.slotsPath();
+            mkdirSync(dirname(p), { recursive: true });
+            const tmp = `${p}.tmp`;
+            writeFileSync(tmp, JSON.stringify(uuids));
+            renameSync(tmp, p);
+        }
+        catch (e) {
+            prodLog?.warn?.(`NativeDiskAnnWrapper: failed to persist slot map: ${String(e)}`);
+        }
+    }
+    /**
+     * Rehydrate `slotByUuid`/`uuidBySlot` from the persisted slot map. Returns
+     * `false` (caller discards the loaded index) when the map is absent or
+     * unreadable — the native index alone cannot map slots → entity IDs.
+     */
+    loadSlots() {
+        try {
+            const p = this.slotsPath();
+            if (!existsSync(p))
+                return false;
+            const uuids = JSON.parse(readFileSync(p, 'utf8'));
+            if (!Array.isArray(uuids))
+                return false;
+            const slotByUuid = new Map();
+            const uuidBySlot = new Map();
+            for (let i = 0; i < uuids.length; i++) {
+                slotByUuid.set(uuids[i], i);
+                uuidBySlot.set(i, uuids[i]);
+            }
+            this.slotByUuid = slotByUuid;
+            this.uuidBySlot = uuidBySlot;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * **Piece I.** Resolve the open-time mode for an existing file.
+     * Respects an explicit `config.mode` override; otherwise consults
+     * the adaptive selector.
+     */
+    resolveOpenMode(stats) {
+        const explicit = this.config.mode;
+        if (explicit !== 'auto') {
+            // Synthesise a minimal ModeSelection so telemetry callers
+            // still see a populated lastSelection. estimatedBytes left
+            // at 0 — the override skipped the cost calc.
+            return {
+                mode: explicit,
+                selection: {
+                    mode: explicit,
+                    reason: 'no-pq-file',
+                    estimatedBytes: 0,
+                    perBrainAvailable: 0,
+                },
+            };
+        }
+        const selection = selectModeFromResourceManager(stats);
+        return { mode: selection.mode, selection };
+    }
+    /**
+     * **Piece I.** Resolve the build-time mode. Same override-respecting
+     * shape as {@link resolveOpenMode}; the build-time decision
+     * additionally lets the selector choose Mode 1 (no PQ) when the
+     * brain fits in RAM.
+     */
+    resolveBuildMode(stats) {
+        const explicit = this.config.mode;
+        if (explicit !== 'auto') {
+            return {
+                mode: explicit,
+                selection: {
+                    mode: explicit,
+                    reason: explicit === 'in-memory' ? 'fits-in-memory' : 'codes-pinned',
+                    estimatedBytes: 0,
+                    perBrainAvailable: 0,
+                },
+            };
+        }
+        const selection = selectModeFromResourceManager(stats);
+        return { mode: selection.mode, selection };
+    }
+    /**
+     * **Piece I.** The selector's most recent decision (either at the
+     * last `tryOpenExisting` or `rebuild`). Returns `null` if no
+     * brain has been opened or built yet. Surface for telemetry and
+     * tests.
+     */
+    getLastModeSelection() {
+        return this.lastSelection;
+    }
+    /**
+     * **Test-only hook** for exercising the build-adjacency resolver
+     * without spinning up a real build. Mirrors the
+     * `_testInjectOsMemoryProbe` pattern (Piece J); not part of the
+     * public contract.
+     * @internal
+     */
+    _testResolveAdjacencyBackend(nodeCount) {
+        return this.resolveAdjacencyBackend(nodeCount);
+    }
+    /**
+     * Resolve the build-time adjacency backend from the config plus
+     * the actual node count. `useMmapAdjacency: 'auto'` (the default)
+     * picks file-backed once `nodeCount > MMAP_ADJACENCY_AUTO_THRESHOLD`;
+     * explicit `true` / `false` always wins. Per the zero-config
+     * principle, operators don't have to know the 100 M threshold —
+     * the wrapper observes `totalCount` and flips automatically.
+     */
+    resolveAdjacencyBackend(nodeCount) {
+        const setting = this.config.useMmapAdjacency;
+        const useMmap = setting === 'auto'
+            ? nodeCount > MMAP_ADJACENCY_AUTO_THRESHOLD
+            : setting === true;
+        if (useMmap) {
+            return {
+                kind: 'mmap',
+                mmapPath: this.config.mmapAdjacencyPath ?? `${this.config.indexPath}.adj`,
+            };
+        }
+        return { kind: 'ram' };
+    }
+    countMainTombstones() {
+        let n = 0;
+        for (const uuid of this.tombstones) {
+            if (this.slotByUuid.has(uuid))
+                n++;
+        }
+        return n;
+    }
+}
+//# sourceMappingURL=NativeDiskAnnWrapper.js.map