@soulcraft/cor 3.0.0-rc.1

package/dist/hnsw/NativeDiskAnnWrapper.js

@@ -0,0 +1,1456 @@
+/**
+ * @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', path: '/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', path: '/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 of the **whole walked
+ *      candidate list** by default (`paddingFactor` is an optional cap
+ *      for bounding cold-NVMe re-rank I/O — see {@link RECALL_PRESETS}).
+ * 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, existsSync, rmSync } 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;
+/**
+ * **Delta budget (the MVP-A bound).** The in-memory delta absorbs writes
+ * between folds; unbounded, it is an OOM risk and a growing brute-force
+ * search cost. At the SOFT threshold the wrapper kicks a BACKGROUND fold
+ * (the async rebuild — serving and writes continue); at the HARD cap
+ * `addItem()` applies backpressure by awaiting the in-flight fold before
+ * accepting the write — bounded memory, never a silent stall. Sized in
+ * bytes so dimensionality doesn't change the memory story (64 MB ≈ 44 K
+ * vectors at dim 384). The #73 LSM-segment work (MVP-C) replaces the O(N)
+ * fold behind these SAME triggers with an O(delta) L0 segment flush.
+ */
+const DELTA_SOFT_FOLD_BYTES = 64 * 1024 * 1024;
+const DELTA_HARD_CAP_BYTES = 256 * 1024 * 1024;
+/**
+ * **#73 MVP-C — LSM-tiered immutable vector segments.** The delta no longer
+ * folds into the main index with an O(N) rebuild: it flushes into a small
+ * immutable L0 SEGMENT (`seg-<id>.dkann`, built from the delta alone —
+ * O(new-data), seconds not days). Search fans out over base + L0 segments +
+ * delta with first-seen-by-uuid dedup (newest wins). When the L0 count
+ * reaches this threshold, a BACKGROUND consolidation (the async rebuild,
+ * which folds base + L0s + delta into a fresh base) runs — rare, off-thread,
+ * never blocking a read or a write. L0 segments are bounded-small by
+ * construction (each born from a ≤{@link DELTA_SOFT_FOLD_BYTES} delta), so
+ * consolidation reads them back via `readVectorChunk` — bounded RAM.
+ */
+const L0_COMPACT_THRESHOLD = 4;
+/**
+ * Storage key of the vector segment manifest (flat key — slashed keys trip
+ * the storage adapters' unknown-key warning; same lesson as the metadata
+ * LSM's `__metadata_lsm_manifest__`). Records the live L0 segment set +
+ * the next segment id; the base index stays at the canonical `indexPath`.
+ * Crash-ordering invariant (ported from the graph index): the segment FILE
+ * is fully written before the manifest references it, and superseded files
+ * are deleted only AFTER the manifest stops referencing them — a crash
+ * leaves orphan files, never a manifest pointing at a missing segment.
+ */
+const VECTOR_MANIFEST_KEY = '__vector_index_manifest__';
+/**
+ * **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`) sets
+ * the search-time `defaultLSearch` — the candidate-walk width, which
+ * is the recall/latency dial. None of the presets cap the re-rank:
+ * the searcher exact-scores the **full walked candidate list** by
+ * default (the mmap-resident vectors make that near-free), so a wider
+ * `l_search` directly buys recall. `defaultPaddingFactor` stays an
+ * optional override (escape hatch for bounding re-rank I/O on
+ * cold-NVMe billion-scale indexes); when omitted, re-rank is full-list.
+ *
+ * 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 },
+    balanced: { defaultLSearch: 100 },
+    accurate: { defaultLSearch: 200 },
+};
+/**
+ * @description **Scale-aware `l_search` (E3 zero-config adaptation).** The walk
+ * width a fixed default serves degrades with corpus size: recall@10 at
+ * `l_search=100` MEASURED 0.9942 @ 1M → 0.9385 @ 10M → **0.8747 @ 100M**
+ * (SIFT sweeps, bxl9000 2026-07-01: sift10m-recall + sift100m-nvme runs;
+ * summaries in `docs/verification/`). Holding ≥0.95 needed `l_search≈150` at
+ * 10M (0.9647) and `≈256` at 100M (0.9559) — i.e. the required width grows
+ * ~×1.8 per decade of corpus size. This resolver widens the *default* walk to
+ * match: `base` up to 2M nodes (where the measured recall is ≥0.99 already),
+ * then `base × 1.8^log10(n/2e6)`, capped at 512 (the latency guard; the cap is
+ * also where the 1B PROJECTION ends — 1B ≈ 489 stays a projection until the
+ * SIFT1B run measures it).
+ *
+ * Zero-config contract: this scales the DEFAULT only. An explicit
+ * `defaultLSearch` in the construction config pins the width verbatim (the
+ * escape hatch), and a `recall` preset scales proportionally from its base
+ * (`fast`/`accurate` keep their relative latency/recall intent at every scale).
+ *
+ * @param base - The preset/base walk width (e.g. 100 for 'balanced').
+ * @param nodeCount - Current corpus size (main index + delta).
+ * @returns The scale-adjusted walk width, in `[base, 512]` (never below base).
+ * @example
+ * scaleAwareLSearch(100, 1e6)  // 100  (measured 0.9942 — base is ample)
+ * scaleAwareLSearch(100, 1e7)  // 151  (measured anchor: 150 → 0.9647)
+ * scaleAwareLSearch(100, 1e8)  // 271  (measured anchor: 256 → 0.9559)
+ * scaleAwareLSearch(100, 1e9)  // 489  (PROJECTED — SIFT1B measures it)
+ */
+export function scaleAwareLSearch(base, nodeCount) {
+    const SCALE_FLOOR_N = 2e6; // below this the measured recall is ≥0.99 at base
+    const GROWTH_PER_DECADE = 1.8; // fitted to the 10M/100M measured anchors
+    const CAP = 512; // latency guard + the edge of measured territory
+    if (!(nodeCount > SCALE_FLOOR_N) || base >= CAP)
+        return Math.min(base, CAP) || base;
+    const decades = Math.log10(nodeCount / SCALE_FLOOR_N);
+    const scaled = Math.round(base * Math.pow(GROWTH_PER_DECADE, decades));
+    return Math.max(base, Math.min(CAP, scaled));
+}
+const DEFAULTS = {
+    // 0 = auto-derive m from the observed dimension (target dsub ≈ 8) in
+    // the native build path — see `derivePqM` / native `pqDeriveM`. A
+    // fixed m crushes recall at high dimensions; zero-config picks the
+    // right m per dimension. Pin a non-zero value to override.
+    pqM: 0,
+    pqKsub: 256,
+    maxDegree: 64,
+    searchListSize: 100,
+    alpha: 1.2,
+    defaultLSearch: 100,
+    // defaultPaddingFactor intentionally unset: the searcher re-ranks
+    // the full walked candidate list by default (best recall). It's an
+    // explicit override only — see InternalDefaults.defaultPaddingFactor.
+    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();
+    /**
+     * **#72 Phase A+B — lazy resolver to the canonical entity-id mapper**
+     * (the metadata index's mapper, the SAME one brainy assigns entity
+     * ints with at write time). Wired by `src/plugin.ts` exactly as the
+     * graph index's `mapperResolver` (#68). The wrapper resolves
+     * `uuid → int` (slotmap writes, pushdown, membership) and `int → uuid`
+     * (search-result hydration) through it, which is why there is no
+     * longer a resident `slotByUuid` / `uuidBySlot` pair on the JS heap —
+     * the off-heap mmap slotmaps (`main.slotmap` / `main.slotrev`) plus
+     * this mapper replace them entirely (the 10B-RAM gate).
+     */
+    mapperResolver;
+    /**
+     * Lazy resolver to the shared #18 {@link MigrationCoordinator} (the same getter
+     * the metadata + graph providers receive). Undefined when no migration path is
+     * wired (e.g. a raw-napi construction in tests).
+     */
+    migrationCoordinatorGetter;
+    /**
+     * True when the construction config carried an EXPLICIT `defaultLSearch` —
+     * the operator pinned the walk width, so {@link resolveLSearch} uses it
+     * verbatim instead of the scale-aware default (see {@link scaleAwareLSearch}).
+     * A `recall` preset does NOT pin: presets set the BASE and still scale with
+     * corpus size, preserving their relative recall/latency intent at every scale.
+     */
+    lSearchPinned = false;
+    /**
+     * The in-flight fold (async rebuild) promise, or `null`. Concurrent
+     * `rebuild()` calls coalesce onto it, `addItem()`'s hard-cap backpressure
+     * awaits it, and `removeItem()` consults it so a delta-only removal that
+     * may already be baked into the incoming index still gets a tombstone
+     * (no resurrection at swap).
+     */
+    rebuildInFlight = null;
+    /** In-flight L0 flush, or null (see {@link flushDeltaToL0}). */
+    flushInFlight = null;
+    /** Live L0 segments, ascending by id (oldest first; search iterates newest→oldest). */
+    l0Segments = [];
+    /** Next segment id (persisted in the manifest). */
+    manifestNextId = 1;
+    /** Segment-manifest cold-load memo (see {@link ensureSegments}). */
+    segmentsLoaded = false;
+    segmentsLoading = null;
+    /** Serializes manifest writes: the storage adapter has no per-key write
+     * ordering, so two in-flight saves (a flush racing a consolidation) could
+     * physically land out of order and persist a STALE segment list — losing a
+     * just-flushed segment's only reference after a restart. Each save chains
+     * behind the previous and builds its payload AT EXECUTION TIME. */
+    manifestSaveChain = Promise.resolve();
+    /**
+     * **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 };
+        // An explicit defaultLSearch in the caller's config (not a preset, not the
+        // internal default) pins the walk width — the scale-aware default steps aside.
+        this.lSearchPinned =
+            config.defaultLSearch !== undefined;
+        this.distanceFunction = distanceFunction;
+        this.storage = options.storage ?? null;
+        this.persistMode = options.persistMode ?? 'immediate';
+        this.mapperResolver = options.mapperResolver;
+        this.migrationCoordinatorGetter = options.migrationCoordinator;
+        // Try to open an existing file. If absent, the index stays
+        // empty until the first rebuild() flushes the delta buffer.
+        // No mapper is needed here: the native open attaches the off-heap
+        // slotmaps; slot ↔ uuid resolution happens lazily at query/rebuild
+        // time, after brainy's init has wired the mapper.
+        this.tryOpenExisting();
+    }
+    /**
+     * Resolve the canonical entity-id mapper, or throw if it isn't wired.
+     * Every main-index operation (rebuild, search-result hydration,
+     * pushdown, membership) resolves `slot ↔ uuid` through this mapper +
+     * the off-heap slotmaps; without it the wrapper cannot translate the
+     * native engine's entity ints to UUIDs. In production `src/plugin.ts`
+     * always wires it; the throw surfaces a misconfiguration loudly rather
+     * than silently returning empty results.
+     */
+    mapper() {
+        const m = this.mapperResolver?.();
+        if (!m) {
+            throw new Error('NativeDiskAnnWrapper: entity-id mapper is not available. The ' +
+                'wrapper resolves slot↔uuid through the metadata index\'s ' +
+                'mapper (wired by plugin.ts as `() => ' +
+                'metadataIndexInstance?.getIdMapper()`); construct it with a ' +
+                '`mapperResolver` option.');
+        }
+        return m;
+    }
+    /**
+     * Append an entry to the delta buffer. Persisted by the next
+     * `rebuild()` call, which folds the delta into the main index.
+     */
+    async addItem(item) {
+        const bytesPerVector = this.config.dimensions * 4;
+        // HARD cap — backpressure: the delta may not grow unbounded. Wait for
+        // the in-flight fold (or start one) before accepting the write. Serving
+        // is unaffected — the fold runs off the JS thread and reads keep
+        // flowing while this one caller waits.
+        if (this.delta.size * bytesPerVector >= DELTA_HARD_CAP_BYTES) {
+            // Backpressure awaits a FLUSH — O(delta), seconds — never a
+            // consolidation (hours at scale): flushing DURING a background rebuild is
+            // safe (the rebuild folds only its snapshot; the new segment survives
+            // its retirement filter and the serialized manifest saves keep the
+            // on-disk list consistent).
+            await (this.flushInFlight ?? this.flushDeltaToL0());
+        }
+        if (this.tombstones.has(item.id)) {
+            this.tombstones.delete(item.id);
+        }
+        this.delta.set(item.id, item.vector);
+        // SOFT threshold — kick a BACKGROUND fold. Never blocks this write; a
+        // fold failure is logged loudly and the delta stays intact for retry.
+        if (!this.flushInFlight &&
+            this.delta.size * bytesPerVector >= DELTA_SOFT_FOLD_BYTES) {
+            // #73 MVP-C: the soft trigger flushes the delta into a small immutable
+            // L0 SEGMENT — O(new-data), never O(corpus). Consolidation of the
+            // accumulated L0s into the base happens separately in the background
+            // when L0_COMPACT_THRESHOLD is reached (see runFlushToL0).
+            this.flushDeltaToL0().catch((error) => {
+                prodLog.error(`NativeDiskAnnWrapper: background L0 flush failed (delta ` +
+                    `retained; retries at the next trigger): ` +
+                    `${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+        return item.id;
+    }
+    /**
+     * Mark an entry as removed. Filtered out at search time; physically
+     * removed at the next `rebuild()`.
+     */
+    async removeItem(id) {
+        await this.ensureSegments();
+        const inDelta = this.delta.delete(id);
+        // Main-index membership via the off-heap reverse slotmap: resolve
+        // uuid → entity int through the canonical mapper, then ask native
+        // whether that int has a slot in this shard (#72 Phase B). No
+        // resident `slotByUuid` map.
+        let inMain = false;
+        if (this.native || this.l0Segments.length > 0) {
+            const int = this.mapper().getInt(id);
+            if (int !== undefined)
+                inMain = this.hasIntAnywhere(BigInt(int));
+        }
+        // Tombstone when the entity is in the main index — OR when a fold is in
+        // flight: a delta-only entry may already be baked into the incoming
+        // index (the fold built from a snapshot), so deleting it from the live
+        // delta alone would resurrect it at swap. A tombstone for an entity the
+        // incoming index turns out not to contain is harmless and is cleared by
+        // the next fold's reconciliation.
+        if (inMain || this.rebuildInFlight !== null || this.flushInFlight !== null) {
+            this.tombstones.add(id);
+        }
+        return inDelta || inMain;
+    }
+    /**
+     * Hydrate the delta buffer from the canonical nouns persisted in
+     * storage — the cold-rebuild path used by {@link rebuild} after a
+     * `restore()` / migration, when the wrapper has no in-memory state to
+     * fold but storage holds the authoritative records. Streams via
+     * paginated `getNouns()` rather than fetching every noun at once.
+     *
+     * NOTE: like the existing delta path this materializes the vectors it
+     * loads into the JS delta. A billion-noun cold rebuild should instead
+     * stream straight from a storage-backed vector source (the native
+     * `build_from_file` path used by the SIFT billion-scale builder); that
+     * scale optimization is tracked separately. For the migration sizes
+     * this serves today the delta route is correct, and it logs the count
+     * it loaded so an operator can see the reconstruction happen.
+     *
+     * @param dim - Index dimension; nouns whose vector width differs are skipped.
+     */
+    async hydrateDeltaFromStorage(dim) {
+        // Best-effort: only when the storage adapter supports bulk noun reads
+        // (production FileSystemStorage/MmapFileSystemStorage do; some partial
+        // adapters used in direct-construction tests do not). When absent, the
+        // caller falls back to the in-memory rebuild.
+        if (typeof this.storage?.getNouns !== 'function')
+            return;
+        let cursor = undefined;
+        let hasMore = true;
+        let loaded = 0;
+        while (hasMore) {
+            const page = await this.storage.getNouns({ pagination: { limit: 10000, cursor } });
+            for (const noun of page.items) {
+                // Preserve anything restore() already seeded into the delta.
+                if (this.delta.has(noun.id))
+                    continue;
+                // A tombstoned entity must not be resurrected from a stale canonical
+                // record (index-removed-but-noun-present window): the rebuild would
+                // bake it into the new base AND clear its tombstone at reconcile.
+                if (this.tombstones.has(noun.id))
+                    continue;
+                const vector = noun.vector;
+                if (!vector || vector.length !== dim)
+                    continue;
+                this.delta.set(noun.id, vector);
+                loaded++;
+            }
+            hasMore = page.hasMore;
+            cursor = page.nextCursor;
+        }
+        if (loaded > 0) {
+            prodLog?.info?.(`NativeDiskAnnWrapper: cold rebuild hydrated ${loaded} vectors from ` +
+                `canonical storage (#44 migration/restore path)`);
+        }
+    }
+    async search(queryVector, k = 10, filter, options) {
+        // Predicate pushdown: a SELECTIVE metadata∩graph universe is evaluated
+        // INSIDE the native walk rather than dropped afterwards.
+        //
+        // brainy supplies that universe as `allowedIds` (the #46 opaque-producer
+        // path, once cor exposes `getIdSetForFilter`) OR — when the producer isn't
+        // present — as `candidateIds`, a plain id list from its metadata pre-filter
+        // (brainy's fallback). They mean the same thing: restrict the search to these
+        // ids. Honoring `candidateIds` (not just `allowedIds`) is what makes filtered
+        // `find({ query, where })` recall-correct on the cor path — without it the
+        // fallback's restriction was dropped and a selective filter collapsed to the
+        // global top-k (silent recall loss). (#79 / #46 consume-side.)
+        const allowedIds = options?.allowedIds ??
+            (options?.candidateIds && options.candidateIds.length > 0
+                ? new Set(options.candidateIds)
+                : undefined);
+        await this.ensureSegments();
+        if (allowedIds && this.native && allowedIds.size > 0) {
+            const mainSize = this.indexedSize();
+            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 = this.resolveLSearch(k);
+        const padding = options?.rerank?.multiplier ?? this.config.defaultPaddingFactor;
+        const query = Array.from(queryVector);
+        // Fan-out with FIRST-SEEN-BY-UUID dedup, newest source first: an updated
+        // entity may exist in an older segment (or the base) too — the newest
+        // version is authoritative, regardless of which copy scores closer.
+        // Priority: delta (newest) → L0 segments newest→oldest → base.
+        const seen = new Set();
+        const merged = [];
+        // 1. Brute-force the delta buffer (the newest state).
+        for (const [id, v] of this.delta) {
+            seen.add(id); // the delta version supersedes ALL indexed copies
+            if (filter && !(await filter(id)))
+                continue;
+            const d = this.distanceFunction(queryVector, v);
+            merged.push([id, d]);
+        }
+        // 2. Each index (L0 newest→oldest, then base): PQ-greedy walk with a
+        //    k×2 per-segment over-fetch (the multi-shard requirement — an
+        //    under-sampled segment holding several true top-k loses recall),
+        //    hydrated int → uuid through the canonical mapper; tombstoned +
+        //    filter-rejected + already-seen dropped.
+        const engines = [
+            ...[...this.l0Segments].reverse().map((s) => s.native),
+            ...(this.native ? [this.native] : []),
+        ];
+        if (engines.length > 0) {
+            const mapper = this.mapper();
+            for (let e = 0; e < engines.length; e++) {
+                const hits = engines[e].search(query, k * 2, lSearch, padding);
+                for (const hit of hits) {
+                    // AUTHORITY CHECK: first-seen dedup alone is not enough — the newer
+                    // copy only enters `seen` if its segment SURFACED it, and a top-k×2
+                    // truncation on a large segment can miss it (a query near an updated
+                    // entity's OLD position would then serve the stale copy at distance
+                    // ≈0). A copy is authoritative only if NO newer source also indexes
+                    // the entity: probe the newer engines' reverse slotmaps (cheap mmap
+                    // lookups, ≤ segments-1 per hit). The delta (newest of all) is
+                    // covered by the uuid `seen` pre-seed above.
+                    let superseded = false;
+                    for (let j = 0; j < e; j++) {
+                        if (engines[j].hasInt(hit.id)) {
+                            superseded = true;
+                            break;
+                        }
+                    }
+                    if (superseded)
+                        continue;
+                    const uuid = mapper.getUuid(Number(hit.id));
+                    if (!uuid)
+                        continue;
+                    if (seen.has(uuid))
+                        continue;
+                    seen.add(uuid);
+                    if (this.tombstones.has(uuid))
+                        continue;
+                    if (filter && !(await filter(uuid)))
+                        continue;
+                    merged.push([uuid, hit.distance]);
+                }
+            }
+        }
+        // 3. 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 query = Array.from(queryVector);
+        const seen = new Set();
+        const merged = [];
+        // 1. Brute-force the delta buffer (allowed entries only; the newest state
+        //    supersedes every indexed copy — first-seen dedup as in search()).
+        for (const [id, v] of this.delta) {
+            seen.add(id);
+            if (!allowedIds.has(id))
+                continue;
+            if (filter && !(await filter(id)))
+                continue;
+            const d = this.distanceFunction(queryVector, v);
+            merged.push([id, d]);
+        }
+        // 2. Native filtered walk over EACH index (L0 newest→oldest, then base;
+        //    allowed slots only, translated per segment through ITS reverse
+        //    slotmap — `slotsForInts` drops ints not in that segment, so each
+        //    fan-out sees exactly its own allowed slot set).
+        const engines = [
+            ...[...this.l0Segments].reverse().map((s) => s.native),
+            ...(this.native ? [this.native] : []),
+        ];
+        if (engines.length > 0) {
+            const mapper = this.mapper();
+            const allowedInts = [];
+            for (const id of allowedIds) {
+                const int = mapper.getInt(id);
+                if (int !== undefined)
+                    allowedInts.push(BigInt(int));
+            }
+            for (let e = 0; e < engines.length; e++) {
+                const engine = engines[e];
+                const allowedSlots = allowedInts.length > 0 ? engine.slotsForInts(allowedInts) : [];
+                if (allowedSlots.length === 0)
+                    continue;
+                const engineSize = engine.size();
+                const selectivity = allowedSlots.length / Math.max(1, engineSize);
+                // 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). Small L0
+                // segments almost always take this path — recall 1.0 by construction.
+                const useBrute = allowedSlots.length <= PUSHDOWN_BRUTE_MAX_ALLOWED || idealL > PUSHDOWN_MAX_LSEARCH;
+                let hits;
+                if (useBrute) {
+                    hits = engine.searchExactSlots(query, nativeK, allowedSlots);
+                }
+                else {
+                    const lSearch = Math.max(this.resolveLSearch(k), idealL);
+                    hits = engine.searchFiltered(query, nativeK, allowedSlots, lSearch, padding);
+                }
+                for (const hit of hits) {
+                    // AUTHORITY CHECK — see search(): a copy is authoritative only when
+                    // no newer source indexes the same entity.
+                    let superseded = false;
+                    for (let j = 0; j < e; j++) {
+                        if (engines[j].hasInt(hit.id)) {
+                            superseded = true;
+                            break;
+                        }
+                    }
+                    if (superseded)
+                        continue;
+                    const uuid = mapper.getUuid(Number(hit.id));
+                    if (!uuid)
+                        continue;
+                    if (seen.has(uuid))
+                        continue;
+                    seen.add(uuid);
+                    if (this.tombstones.has(uuid))
+                        continue;
+                    if (filter && !(await filter(uuid)))
+                        continue;
+                    merged.push([uuid, hit.distance]);
+                }
+            }
+        }
+        // 3. Sort ascending by distance, truncate to k.
+        merged.sort((a, b) => a[1] - b[1]);
+        return merged.slice(0, k);
+    }
+    /**
+     * @description **#18 migration lock — feature-detected by Brainy.** `true` while
+     * the brain is undergoing (or has failed) the coordinated 7.x → 8.0 rebuild, so
+     * Brainy holds reads+writes behind the lock (and skips its lazy first-query
+     * force-rebuild of the vector index). Delegates to the shared {@link
+     * MigrationCoordinator}; `false` when none is wired.
+     * @returns `true` when the brain must not be read from or written to.
+     */
+    isMigrating() {
+        return this.migrationCoordinatorGetter?.()?.isMigrating() ?? false;
+    }
+    /**
+     * @description **#18 migration lock — structured progress** Brainy relays into
+     * `getIndexStatus().migration`. `null` unless a migration is in flight.
+     * @returns The current {@link MigrationStatus}, or `null`.
+     */
+    migrationStatus() {
+        return this.migrationCoordinatorGetter?.()?.migrationStatus() ?? null;
+    }
+    /**
+     * @description Resolve the search-time walk width for this query: the
+     * scale-aware default ({@link scaleAwareLSearch} over the current corpus size)
+     * unless the operator pinned `defaultLSearch` explicitly, floored at `k × 2`
+     * so a large `k` is never starved. This is the E3 fix for the measured
+     * fixed-default recall fade (0.9942 @ 1M → 0.8747 @ 100M at l_search=100).
+     * @param k - The requested result count.
+     * @returns The walk width to pass to the native searcher.
+     */
+    /**
+     * **Adaptive DiskANN mode selection (Piece I)** — build the native config for
+     * an index of `totalCount` vectors: the selector picks "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. Shared by the full
+     * consolidation ({@link runRebuild}) and the O(delta) L0 segment flush
+     * ({@link runFlushToL0}); records the selection on {@link lastSelection}.
+     */
+    nativeBuildCfg(totalCount, dim) {
+        const maxDegree = this.config.maxDegree;
+        const buildMode = this.resolveBuildMode({
+            nodeCount: totalCount,
+            dim,
+            maxDegree,
+        });
+        this.lastSelection = buildMode.selection;
+        return {
+            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),
+            },
+        };
+    }
+    resolveLSearch(k) {
+        const base = this.config.defaultLSearch;
+        const width = this.lSearchPinned ? base : scaleAwareLSearch(base, this.size());
+        return Math.max(width, k * 2);
+    }
+    /** Total entries across the base index + all L0 segments (no delta). */
+    indexedSize() {
+        let n = this.native ? this.native.size() : 0;
+        for (const seg of this.l0Segments)
+            n += seg.nodeCount;
+        return n;
+    }
+    size() {
+        return (this.indexedSize() +
+            this.delta.size -
+            // Tombstones against indexed entries reduce effective size. (Before
+            // the async segment cold-load has run, L0 counts are not yet included
+            // — same visibility a fresh single-index open had; ensureSegments()
+            // completes it on the first async operation or provider init().)
+            this.countMainTombstones());
+    }
+    clear() {
+        this.delta.clear();
+        this.tombstones.clear();
+        this.native = null;
+        this.l0Segments = [];
+        // Keep the segment memo LOADED: clear() is an in-process reset (the base
+        // stays null until a reopen too) — resetting the memo would resurrect the
+        // cleared L0s from the manifest at the next async op, and a subsequent
+        // rebuild() would fold the "cleared" entries back in permanently.
+        this.segmentsLoaded = true;
+        this.segmentsLoading = 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-to-days of
+     * build time) — but it is NON-BLOCKING: the build runs on a worker
+     * thread (`rebuildFromExistingAsync`), so the JS event loop keeps
+     * serving reads and accepting writes for the entire fold. Writes that
+     * land mid-fold stay in the live delta (reconciled against the fold's
+     * snapshot at swap) and roll into the next fold. Concurrent calls
+     * coalesce onto the in-flight fold. The delta is bounded: a soft
+     * threshold kicks a background fold automatically and a hard cap
+     * applies backpressure in `addItem` (see `DELTA_SOFT_FOLD_BYTES`).
+     *
+     * 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) {
+        // Concurrent rebuilds COALESCE: a call while a fold is in flight awaits
+        // that same completion (its options are ignored — idempotent-concurrent
+        // semantics, so brainy's coordinated rebuild, the #18 migration, and the
+        // delta auto-fold can race here safely without double-building).
+        if (this.rebuildInFlight)
+            return this.rebuildInFlight;
+        const run = this.runRebuild(options).finally(() => {
+            this.rebuildInFlight = null;
+        });
+        this.rebuildInFlight = run;
+        return run;
+    }
+    /** The fold body — see {@link rebuild} for the public contract. */
+    async runRebuild(options) {
+        await this.ensureSegments();
+        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."
+        //
+        // #72 Phase A+B: there is no resident `slot ↔ uuid` map any more.
+        // The surviving old slots are derived from the native node count
+        // (ascending slot order, deterministic — keeps the Vamana entry
+        // point + on-disk locality stable across rebuilds), minus the slots
+        // of tombstoned entities (resolved uuid → int → slot through the
+        // canonical mapper + the off-heap reverse slotmap). Their stable
+        // entity ints come straight from the old forward slotmap and carry
+        // into the new one.
+        // Snapshot the fold's input sets. Writes that land while the ASYNC
+        // build runs stay in the live delta/tombstones and are reconciled after
+        // the swap — they belong to the NEXT fold.
+        const builtTombstones = new Set(this.tombstones);
+        // #73 MVP-C: snapshot the live L0 segments — this consolidation folds them
+        // into the new base. Their entries are read back through the existing
+        // readVectorChunk/slotIdsForSlots surface (each segment is bounded-small
+        // by construction, ≤ the delta budget, so this stays bounded RAM).
+        const builtL0 = [...this.l0Segments];
+        const l0Data = builtL0.map((seg) => ({
+            ints: (seg.nodeCount > 0
+                ? seg.native.slotIdsForSlots(Array.from({ length: seg.nodeCount }, (_, i) => i))
+                : []),
+            vecs: seg.native.readVectorChunk(0, seg.nodeCount),
+        }));
+        // Tombstone ints (used to exclude entries from BOTH the base and the L0
+        // read-back). Ids never indexed have no int — nothing to exclude.
+        const tombIntKeys = new Set();
+        if (builtTombstones.size > 0 && (this.native || builtL0.length > 0)) {
+            const mapper = this.mapper();
+            for (const uuid of builtTombstones) {
+                const int = mapper.getInt(uuid);
+                if (int !== undefined)
+                    tombIntKeys.add(BigInt(int).toString());
+            }
+        }
+        const liveOldSlots = [];
+        let oldInts = [];
+        if (this.native) {
+            const oldNodeCount = this.native.size();
+            // Exclude from the surviving base slots: tombstoned entities, entities
+            // SUPERSEDED by an L0 copy (newer), and entities with a live delta copy
+            // (newest) — otherwise the merged index would carry duplicate entity
+            // ints, corrupting the reverse slotmap. Newest-wins, enforced here.
+            const excludeKeys = new Set(tombIntKeys);
+            for (const d of l0Data) {
+                for (const i of d.ints)
+                    excludeKeys.add(i.toString());
+            }
+            if (this.delta.size > 0) {
+                const mapper = this.mapper();
+                for (const uuid of this.delta.keys()) {
+                    const int = mapper.getInt(uuid);
+                    if (int !== undefined)
+                        excludeKeys.add(BigInt(int).toString());
+                }
+            }
+            const excludedSlots = new Set();
+            if (excludeKeys.size > 0) {
+                const excludeInts = [...excludeKeys].map((k) => BigInt(k));
+                for (const slot of this.native.slotsForInts(excludeInts)) {
+                    excludedSlots.add(slot);
+                }
+            }
+            for (let s = 0; s < oldNodeCount; s++) {
+                if (!excludedSlots.has(s))
+                    liveOldSlots.push(s);
+            }
+            oldInts =
+                liveOldSlots.length > 0 ? this.native.slotIdsForSlots(liveOldSlots) : [];
+        }
+        // #44 migration / cold-rebuild from canonical storage. brainy's
+        // `restore()` reconstructs the vector index by calling `rebuild()`
+        // directly (`this.index` IS this wrapper), but a freshly-opened
+        // wrapper over the restored dir has no loaded native index — the
+        // canonical noun vectors live only in storage, and restore() does NOT
+        // re-feed them through addItem (it may seed only a straggler such as
+        // the VFS root). Without this the rebuilt index comes back missing its
+        // entities and post-migration vector search silently returns nothing
+        // (the migrate script's count-based verify can't catch it).
+        //
+        // Fires ONLY when there is no surviving main index AND storage holds
+        // more nouns than the in-memory working set — i.e. a cold/restore
+        // rebuild that would otherwise drop canonical vectors. A normal first
+        // build (delta already covers every persisted noun) and a live rebuild
+        // (non-empty `liveOldSlots`) both skip it, so the hot paths pay
+        // nothing. `hydrateDeltaFromStorage` only adds ids absent from the
+        // delta, so any straggler already fed by restore is preserved.
+        if (liveOldSlots.length === 0 && typeof this.storage?.getNouns === 'function') {
+            const probe = await this.storage.getNouns({ pagination: { limit: 1 } });
+            if (probe.totalCount === undefined || probe.totalCount > this.delta.size) {
+                await this.hydrateDeltaFromStorage(this.config.dimensions);
+            }
+        }
+        // Delta snapshot AFTER the cold-hydrate (which populates this.delta).
+        const builtDelta = new Map(this.delta);
+        const dim = this.config.dimensions;
+        const deltaCount = builtDelta.size;
+        let deltaBuf = null;
+        const deltaInts = [];
+        if (deltaCount > 0) {
+            const mapper = this.mapper();
+            deltaBuf = new Float32Array(deltaCount * dim);
+            let idx = 0;
+            for (const [uuid, vector] of builtDelta) {
+                if (vector.length !== dim) {
+                    throw new Error(`NativeDiskAnnWrapper.rebuild: vector dim ${vector.length} ≠ index dim ${dim}`);
+                }
+                deltaBuf.set(vector, idx * dim);
+                // Entity int for this delta uuid. In production the canonical
+                // mapper already assigned it at metadata write time, so
+                // getOrAssign returns that existing int (the unit-test mapper
+                // assigns on demand) — keeping the slotmap, bitmaps, and graph
+                // endpoints on one 0-based int space.
+                deltaInts.push(BigInt(mapper.getOrAssign(uuid)));
+                idx++;
+            }
+        }
+        // #73: the L0 entries that survive dedup — newest segment wins, the delta
+        // wins over every segment, tombstoned entities drop.
+        const deltaIntKeys = new Set(deltaInts.map((i) => i.toString()));
+        const l0Entries = [];
+        {
+            const seenL0 = new Set();
+            for (let sIdx = builtL0.length - 1; sIdx >= 0; sIdx--) {
+                const ints = l0Data[sIdx].ints;
+                for (let r = 0; r < ints.length; r++) {
+                    const key = ints[r].toString();
+                    if (seenL0.has(key) || deltaIntKeys.has(key) || tombIntKeys.has(key))
+                        continue;
+                    seenL0.add(key);
+                    l0Entries.push({ int: ints[r], seg: sIdx, row: r });
+                }
+            }
+        }
+        if (liveOldSlots.length + deltaCount + l0Entries.length === 0) {
+            prodLog?.warn?.('NativeDiskAnnWrapper.rebuild: nothing to build');
+            return;
+        }
+        const totalCount = liveOldSlots.length + deltaCount + l0Entries.length;
+        // Apply optional recall override for this rebuild only.
+        if (options?.recall) {
+            const preset = RECALL_PRESETS[options.recall];
+            this.config = { ...this.config, ...preset };
+        }
+        const { cfg } = this.nativeBuildCfg(totalCount, dim);
+        // 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 });
+        // Per-slot entity ints for the new index: [live old ints..., delta
+        // ints...] — slot `i` ↔ `slotIds[i]`, matching the native
+        // MergedVectorSource layout (live old slots first, delta tail
+        // second). The native side writes this into the off-heap forward +
+        // reverse slotmaps atomically with the new `.dkann`.
+        // Merged tail = [delta entries..., deduped L0 entries...]. Slot i maps to
+        // [live old slots..., tail...] in the MergedVectorSource layout; slotIds
+        // aligns 1:1 with that order.
+        const tailCount = deltaCount + l0Entries.length;
+        const tailBuf = new Float32Array(tailCount * dim);
+        if (deltaBuf)
+            tailBuf.set(deltaBuf, 0);
+        for (let e = 0; e < l0Entries.length; e++) {
+            const { seg, row } = l0Entries[e];
+            const vecs = l0Data[seg].vecs;
+            const view = new Float32Array(vecs.buffer, vecs.byteOffset + row * dim * 4, dim);
+            tailBuf.set(view, (deltaCount + e) * dim);
+        }
+        const totalSlotInts = liveOldSlots.length + tailCount;
+        const slotIdsArr = new BigUint64Array(totalSlotInts);
+        for (let i = 0; i < oldInts.length; i++)
+            slotIdsArr[i] = oldInts[i];
+        for (let i = 0; i < deltaInts.length; i++) {
+            slotIdsArr[oldInts.length + i] = deltaInts[i];
+        }
+        for (let e = 0; e < l0Entries.length; e++) {
+            slotIdsArr[oldInts.length + deltaCount + e] = l0Entries[e].int;
+        }
+        const slotIdsBuf = Buffer.from(slotIdsArr.buffer, slotIdsArr.byteOffset, slotIdsArr.byteLength);
+        // The heavy build runs on a worker thread (AsyncTask): the JS event
+        // loop keeps serving reads AND accepting writes for the entire fold —
+        // hours-to-days at billion scale, zero freeze.
+        const newNative = await NativeDiskANN.rebuildFromExistingAsync({
+            existingPath: this.native ? this.config.indexPath : undefined,
+            liveOldSlots,
+            deltaVectors: tailCount > 0
+                ? Buffer.from(tailBuf.buffer, tailBuf.byteOffset, tailBuf.byteLength)
+                : undefined,
+            deltaCount: tailCount,
+            dim,
+            outputPath: this.config.indexPath,
+            cfg,
+            slotIds: slotIdsBuf,
+        });
+        // Atomic swap. The native engine now owns both off-heap slotmaps
+        // (written inside rebuildFromExisting), so there is NO resident
+        // `slot ↔ uuid` map to reconstruct and NO `.slots.json` to persist —
+        // the #72 Phase A+B win. slot ↔ uuid resolution flows through the
+        // mmap slotmaps + the canonical mapper on every query.
+        this.native = newNative;
+        // Reconcile the LIVE delta/tombstones against the fold snapshot: only
+        // entries the fold actually baked in are cleared. Adds/updates/removes
+        // that landed during the async build stay behind for the next fold (an
+        // id UPDATED mid-fold keeps its new vector — reference inequality
+        // detects the overwrite).
+        for (const [id, vector] of builtDelta) {
+            if (this.delta.get(id) === vector)
+                this.delta.delete(id);
+        }
+        for (const id of builtTombstones)
+            this.tombstones.delete(id);
+        // #73: the consolidation folded the snapshot L0 segments into the new
+        // base. Manifest FIRST drops the references, THEN the files are deleted
+        // (the graph index's crash-ordering invariant: a crash between the two
+        // leaves orphan files, never a manifest pointing at a missing segment).
+        // L0 segments created by a concurrent flush DURING this build are not in
+        // the snapshot and survive untouched.
+        if (builtL0.length > 0) {
+            this.l0Segments = this.l0Segments.filter((seg) => !builtL0.includes(seg));
+            await this.saveSegmentManifest();
+            for (const seg of builtL0) {
+                for (const suffix of ['.dkann', '.slotmap', '.slotrev']) {
+                    try {
+                        rmSync(this.segPath(seg.file).replace(/\.dkann$/, suffix));
+                    }
+                    catch {
+                        // best-effort orphan cleanup — leaked bytes, never a correctness issue
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * 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;
+    }
+    /** Absolute path of a segment file (lives next to the base indexPath). */
+    segPath(file) {
+        return `${dirname(this.config.indexPath)}/${file}`;
+    }
+    /** Membership across the base + every L0 segment (int → any slot). */
+    hasIntAnywhere(int) {
+        if (this.native && this.native.hasInt(int))
+            return true;
+        for (const seg of this.l0Segments) {
+            if (seg.native.hasInt(int))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * @description Provider init — brainy feature-detects and awaits it. Cold-loads
+     * the segment manifest so a reopened brain serves its L0 segments from the
+     * first query (the wrapper's own async paths also call {@link ensureSegments},
+     * so a caller that skips init() still gets the segments lazily).
+     */
+    async init() {
+        await this.ensureSegments();
+    }
+    /** Memoized segment-manifest cold-load. */
+    async ensureSegments() {
+        if (this.segmentsLoaded)
+            return;
+        if (this.segmentsLoading)
+            return this.segmentsLoading;
+        this.segmentsLoading = this.loadSegmentManifest().finally(() => {
+            this.segmentsLoaded = true;
+            this.segmentsLoading = null;
+        });
+        return this.segmentsLoading;
+    }
+    /**
+     * Read `__vector_index_manifest__` and open every live L0 segment. A missing
+     * manifest is the legacy single-index layout (the base at `indexPath` IS the
+     * whole vector index) — existing brains upgrade seamlessly; the first flush
+     * writes the first manifest. A segment file the manifest references but that
+     * fails to open is SKIPPED loudly (crash-orphan tolerance; its entries remain
+     * safe in canonical storage and the next consolidation heals the set).
+     */
+    async loadSegmentManifest() {
+        const storage = this.storage;
+        if (!storage || typeof storage.getMetadata !== 'function')
+            return;
+        let manifest = null;
+        try {
+            const raw = await storage.getMetadata(VECTOR_MANIFEST_KEY);
+            manifest = raw?.data ?? null;
+        }
+        catch {
+            return; // unreadable manifest = legacy layout; the next flush rewrites it
+        }
+        if (!manifest)
+            return;
+        this.manifestNextId = Math.max(1, Number(manifest.nextId) || 1);
+        const bindings = loadNativeModule();
+        const NativeDiskANN = bindings.NativeDiskAnn;
+        if (!NativeDiskANN)
+            return;
+        for (const entry of manifest.l0 ?? []) {
+            try {
+                const native = NativeDiskANN.openExisting(this.segPath(entry.file));
+                if (!native.slotmapReady())
+                    throw new Error('segment slotmap missing');
+                this.l0Segments.push({ ...entry, native });
+            }
+            catch (error) {
+                prodLog.warn(`NativeDiskAnnWrapper: skipping unreadable L0 segment ${entry.file} ` +
+                    `(${error instanceof Error ? error.message : String(error)}) — its ` +
+                    `entries remain in canonical storage; consolidation heals the set`);
+            }
+        }
+    }
+    /**
+     * Persist the live segment set (AFTER the referenced files exist on disk).
+     * Saves are SERIALIZED and each snapshot the segment list at write time, so
+     * concurrent flush/consolidation saves can never persist out of order.
+     */
+    saveSegmentManifest() {
+        const next = this.manifestSaveChain.then(() => this.writeSegmentManifestNow());
+        // The chain must survive a failed save (the failure still propagates to
+        // THIS caller through `next`).
+        this.manifestSaveChain = next.catch(() => { });
+        return next;
+    }
+    async writeSegmentManifestNow() {
+        const storage = this.storage;
+        if (!storage || typeof storage.saveMetadata !== 'function')
+            return;
+        await storage.saveMetadata(VECTOR_MANIFEST_KEY, {
+            noun: 'thing',
+            data: {
+                version: 1,
+                nextId: this.manifestNextId,
+                l0: this.l0Segments.map(({ id, file, nodeCount }) => ({ id, file, nodeCount })),
+            },
+        });
+    }
+    /**
+     * @description **#73 MVP-C — flush the delta into a new immutable L0 segment.**
+     * O(new-data): builds a small self-contained `.dkann` from the delta snapshot
+     * alone (existing index untouched), registers it in the manifest, and
+     * reconciles the live delta. Concurrent calls coalesce. Crash ordering: the
+     * segment file is fully written (with its slotmap sidecars) BEFORE the
+     * manifest references it.
+     */
+    flushDeltaToL0() {
+        if (this.flushInFlight)
+            return this.flushInFlight;
+        const run = this.runFlushToL0().finally(() => {
+            this.flushInFlight = null;
+        });
+        this.flushInFlight = run;
+        return run;
+    }
+    /** The flush body — see {@link flushDeltaToL0}. */
+    async runFlushToL0() {
+        await this.ensureSegments();
+        const bindings = loadNativeModule();
+        const NativeDiskANN = bindings.NativeDiskAnn;
+        if (!NativeDiskANN) {
+            throw new Error('NativeDiskANN binding missing — L0 flush requires the cor native module');
+        }
+        const builtDelta = new Map(this.delta);
+        if (builtDelta.size === 0)
+            return;
+        const dim = this.config.dimensions;
+        const mapper = this.mapper();
+        const deltaBuf = new Float32Array(builtDelta.size * dim);
+        const slotIdsArr = new BigUint64Array(builtDelta.size);
+        let idx = 0;
+        for (const [uuid, vector] of builtDelta) {
+            if (vector.length !== dim) {
+                throw new Error(`NativeDiskAnnWrapper.flushDeltaToL0: vector dim ${vector.length} ≠ index dim ${dim}`);
+            }
+            deltaBuf.set(vector, idx * dim);
+            slotIdsArr[idx] = BigInt(mapper.getOrAssign(uuid));
+            idx++;
+        }
+        const id = this.manifestNextId++;
+        const file = `seg-${id}.dkann`;
+        mkdirSync(dirname(this.config.indexPath), { recursive: true });
+        const { cfg } = this.nativeBuildCfg(builtDelta.size, dim);
+        const newNative = await NativeDiskANN.rebuildFromExistingAsync({
+            existingPath: undefined,
+            liveOldSlots: [],
+            deltaVectors: Buffer.from(deltaBuf.buffer, deltaBuf.byteOffset, deltaBuf.byteLength),
+            deltaCount: builtDelta.size,
+            dim,
+            outputPath: this.segPath(file),
+            cfg,
+            slotIds: Buffer.from(slotIdsArr.buffer, slotIdsArr.byteOffset, slotIdsArr.byteLength),
+        });
+        // File (+ sidecars) durably on disk → register → manifest (crash-safe order).
+        this.l0Segments.push({ id, file, nodeCount: builtDelta.size, native: newNative });
+        await this.saveSegmentManifest();
+        // Reconcile the LIVE delta against the flush snapshot (same rule as the
+        // consolidation fold): only unchanged entries clear; an id updated
+        // mid-flush keeps its newer vector for the next flush. Tombstones are NOT
+        // cleared — they still mask the base and, now, this segment's stale copies.
+        for (const [uuid, vector] of builtDelta) {
+            if (this.delta.get(uuid) === vector)
+                this.delta.delete(uuid);
+        }
+        prodLog.info(`NativeDiskAnnWrapper: flushed ${builtDelta.size} delta entries to L0 segment ${file} ` +
+            `(${this.l0Segments.length} live segments)`);
+        // Tiered maintenance: enough small segments → one BACKGROUND consolidation
+        // (the async rebuild folds base + L0s + delta into a fresh base off-thread).
+        if (this.l0Segments.length >= L0_COMPACT_THRESHOLD && !this.rebuildInFlight) {
+            this.rebuild().catch((error) => {
+                prodLog.error(`NativeDiskAnnWrapper: background consolidation failed (segments ` +
+                    `retained; retries at the next trigger): ` +
+                    `${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+    }
+    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;
+            // #72 Phase A+B: the native open attaches the off-heap slot↔int
+            // sidecars (`main.slotmap` / `main.slotrev`). The native engine
+            // stores vectors by slot only, so without a forward slotmap it
+            // can't map hits back to entity ints — discard such an index so
+            // the next rebuild() regenerates both consistently (matches the
+            // old loadSlots()-returned-false behaviour, minus the JS map +
+            // .slots.json parse). No mapper is needed here; slot↔uuid
+            // resolution happens lazily at query/rebuild time.
+            if (!this.native.slotmapReady()) {
+                this.native = null;
+            }
+            else {
+                this.removeLegacySlotsSidecar();
+            }
+        }
+        catch {
+            // No existing file — index stays empty until first rebuild().
+            this.native = null;
+        }
+    }
+    /**
+     * Remove any leftover `main.slots.json` written by a pre-#72 RC build.
+     * The native `main.slotmap` is now authoritative; a stale JSON sidecar
+     * is never read, but we delete it (best-effort) so it can never shadow
+     * the off-heap slotmap and to reclaim its (potentially large) bytes.
+     */
+    removeLegacySlotsSidecar() {
+        try {
+            const legacy = this.config.indexPath.replace(/\.dkann$/, '.slots.json');
+            if (existsSync(legacy))
+                rmSync(legacy, { force: true });
+        }
+        catch {
+            // Best-effort cleanup; a failure here never affects correctness.
+        }
+    }
+    /**
+     * **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' };
+    }
+    /**
+     * Count tombstoned entities that are present in the MAIN index (so
+     * `size()` can subtract them). Membership is the off-heap reverse
+     * slotmap: resolve uuid → int → `hasInt`. Returns 0 without touching
+     * the mapper when there are no tombstones or no main index, so the
+     * common `size()` call stays allocation- and FFI-free.
+     */
+    countMainTombstones() {
+        if (this.tombstones.size === 0 || !this.native)
+            return 0;
+        const mapper = this.mapper();
+        let n = 0;
+        for (const uuid of this.tombstones) {
+            const int = mapper.getInt(uuid);
+            if (int !== undefined && this.hasIntAnywhere(BigInt(int)))
+                n++;
+        }
+        return n;
+    }
+}
+//# sourceMappingURL=NativeDiskAnnWrapper.js.map