@soulcraft/cor 3.0.0-rc.1

package/docs/comparison.md

@@ -0,0 +1,162 @@
+---
+title: How Cor compares
+slug: cor/comparison
+public: true
+category: cor
+template: guide
+order: 2
+description: Side-by-side. Cor 3.0 is the only system that composes metadata + graph + vector with time-travel in one query; index-level latency runs 13–18× pgvector at small-to-medium scale on the reference host (recall-matched, real-data library A/B in progress).
+next:
+  - cor/diskann
+  - cor/performance
+  - guides/plugins
+---
+
+# How Cor compares
+
+> **vs pgvector HNSW** — index-level p50/p99 **latency**, same host
+> (bxl9000: Ryzen 9 7950X3D / NVMe), same dataset + query workload:
+> - 10 K: cor p50 0.048 ms vs pgvector p50 0.865 ms → **18.02×**
+> - 100 K: cor p50 0.041 ms vs pgvector p50 0.536 ms → **13.07×**
+> - 1 M: cor p50 0.148 ms vs pgvector p50 1.081 ms → **7.30×**
+>
+> Cor stays sub-millisecond at p99 even at 1 M (0.309 ms p99 cor vs 1.604 ms p99 pgvector); pgvector crosses 1 ms p99 at this scale.
+>
+> **Read this as latency, not a blanket "faster":** a latency ratio is only
+> meaningful when both engines sit at the same recall. The recall-matched
+> comparison on real-manifold data (SIFT/BIGANN) is being measured in the
+> library A/B; treat these as cor's index-level latency headroom on this
+> reference host, not an end-to-end product claim.
+>
+> Source: `scripts/verify-vs-pgvector.mjs` · result JSON in `docs/verification/`
+
+> **Cor's acceleration of Brainy (isolated-operation micro-benchmarks):**
+> 5.2× geometric mean across 15 *isolated* operations on bxl9000
+> (Embedding 2.8× · Infrastructure 7.8× · Search 25.2× · Data ops 7.3×).
+> This is per-operation acceleration measured in isolation — **not** an
+> end-to-end `find()` speedup. The end-to-end library A/B (brainy-alone vs
+> brainy+cor through the public `find()` path, recall@10 on SIFT) is in
+> progress; that table will be the headline product number.
+
+## Where cor genuinely leads
+
+Most vector databases can do vector ANN. A few can filter by metadata. Almost
+none can hop graph edges. **None** can do all three in a single sub-
+millisecond query AND support point-in-time reads. Cor is the only
+system in that category:
+
+| | Vector ANN | Metadata filter | Graph hop | Time-travel | Triple find() composition |
+|---|:---:|:---:|:---:|:---:|:---:|
+| **Cor 3.0** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| pgvector | ✅ | ✅ (SQL) | partial (SQL JOIN) | ❌ | partial |
+| Qdrant | ✅ | ✅ | ❌ | ❌ | ❌ |
+| Milvus | ✅ | ✅ | ❌ | ❌ | ❌ |
+| Weaviate | ✅ | ✅ | weak | ❌ | ❌ |
+| Pinecone | ✅ | ✅ | ❌ | ❌ | ❌ |
+| FAISS | ✅ | ❌ | ❌ | ❌ | ❌ |
+
+**Triple-find composition at 1 M — per-stage substrate latency:** LSM filter
+16 µs + graph BFS 16 µs + DiskANN 194 µs + JS-side intersection, composing to
+**p50 ≈ 0.230 ms** on bxl9000. Source: `scripts/verify-triple-find.mjs`.
+
+> **Honesty note (being re-validated):** this composition was measured on a
+> *synthetic* corpus, where random vectors are near-orthogonal under cosine
+> (concentration of measure) so the vector leg's recall is ~0 and the composed
+> result set is near-empty. The **per-stage latencies are valid** (each
+> substrate did its work), but the *end-to-end* triple-find latency **and
+> recall** are being re-measured on real-manifold data (SIFT/BIGANN). Treat
+> 0.230 ms as the substrate-composition ceiling, not the validated end-to-end
+> number. Brainy 8.0 also pushes the intersection into native primitives.
+
+
+
+## At a Glance
+
+| Category | Avg Speedup | What it covers |
+|:---------|:------------|:---------------|
+| **Embedding** | **2.8x** | Real ML model inference (all-MiniLM-L6-v2) |
+| **Data Operations** | **7.3x** | Adding, reading, and deleting entities |
+| **Search** | **25.2x** | Finding entities by meaning, filters, and similarity |
+| **Graph** | **1.3x** | Querying relationships between entities |
+| **Neural** | **1.9x** | AI-powered neighbors and clustering |
+
+## Scale Ceiling
+
+The numbers above measure speedup at the 200-entity tier — the "make my queries faster" story. Cor also moves the **scale ceiling itself**: with DiskANN engaged, a single Brainy instance reaches workloads that were previously single-machine impossible.
+
+> **PROJECTED — design targets, not measured.** The table below is extrapolated
+> from algorithm math (Vamana / PQ memory + latency models). Measured numbers
+> at 100M and 1B on real hardware ship in `docs/verification-report.md` as
+> part of Piece 9 of the cor 3.0 release. Per `CLAUDE.md`, perf claims
+> without a `MEASURED` citation must carry a `PROJECTED` label until verified.
+
+| Workload | Brainy alone | Brainy + Cor (HNSW) | Brainy + Cor (DiskANN) |
+|:---|:---|:---|:---|
+| 1 M vectors @ 384-dim | OK, ~1 GB RAM | OK, ~1 GB RAM, 25× faster search | OK, ~0.5 GB RAM, sub-ms search |
+| 10 M vectors | OK, ~15 GB RAM, slow build | OK, ~10 GB RAM | OK, ~3 GB RAM, 1–3 ms search |
+| 100 M vectors | Out of practical reach | OK if you have 100+ GB RAM | OK on a 32 GB box, 2–5 ms search |
+| **1 B vectors** | **Not possible** (1.5 TB RAM) | **Not possible** (1.5+ TB RAM) | **OK on a 64 GB box, 5–10 ms search** |
+
+DiskANN auto-engages when storage is local and a stable idMapper is available — see [docs/diskann.md](./diskann.md). Cloud-storage adapters stay on HNSW transparently.
+
+> Embedding consistency: max element-wise diff = 1.43e-7, avg = 2.64e-8 (WASM and native produce equivalent vectors)
+
+> **Same results, just faster.** Cor accelerates Brainy without changing any
+> answer: native output matches the JavaScript baseline byte-for-byte, enforced by
+> a 104-test cross-language parity suite (tokenization, value normalization,
+> string collation, SQ8 distance, top-K ranking, roaring/msgpack). See
+> [Cor Performance → Cross-Language Consistency](./performance.md).
+
+## Detailed Results
+
+### Embedding
+
+| What it does | WASM | Native Rust | Speedup |
+|:-------------|-----:|------------:|:--------|
+| Engine initialization | 192 ms | 115 ms | **1.7x** |
+| Embed one sentence | 116 ms | 47 ms | **2.4x** |
+| Embed 1 sentence (batch path) | 116 ms | 55 ms | **2.1x** |
+| Embed 10 sentences | 1173 ms | 330 ms | **3.6x** |
+| Embed 20 sentences | 2371 ms | 611 ms | **3.9x** |
+| Embed 50 sentences | 6050 ms | 1577 ms | **3.8x** |
+
+### Data Operations
+
+| What it does | Brainy | + Cor | Speedup |
+|:-------------|-------:|---------:|:--------|
+| Store one entity | 21 ms | 3.0 ms | **7.0x** |
+| Store 20 entities at once | 1384 ms | 110 ms | **12.6x** |
+| Retrieve one entity | 0.001 ms | 0.001 ms | **1.3x** |
+| Remove and re-insert | 113 ms | 4.5 ms | **25.0x** |
+
+### Search
+
+| What it does | Brainy | + Cor | Speedup |
+|:-------------|-------:|---------:|:--------|
+| Search by meaning | 21 ms | 0.4 ms | **50.8x** |
+| Search by fields | 1.9 ms | 0.018 ms | **108.3x** |
+| Find similar items | 0.3 ms | 0.1 ms | **2.9x** |
+
+### Graph
+
+| What it does | Brainy | + Cor | Speedup |
+|:-------------|-------:|---------:|:--------|
+| Query relationships | 0.011 ms | 0.008 ms | **1.3x** |
+
+### Neural
+
+| What it does | Brainy | + Cor | Speedup |
+|:-------------|-------:|---------:|:--------|
+| Nearest neighbors | 0.001 ms | 0.001 ms | **1.9x** |
+| Auto-cluster items | — | — | skipped |
+
+### Embedding Throughput (batch of 50)
+
+| Engine | Texts/sec | ms/text |
+|:-------|----------:|--------:|
+| WASM | 8 | 121.0 |
+| Native Rust | 32 | 31.5 |
+
+---
+
+*Methodology: Infrastructure operations measured 20 times after 3 warmup runs; embedding operations measured 10 times after 2 warmup runs. Reported value is the median. Infrastructure benchmarks use a lightweight hash-based embedding to isolate acceleration from model differences. Embedding benchmarks use the real all-MiniLM-L6-v2 model (384-dim). "Speedup" is the geometric mean of per-operation ratios within each category.*

package/docs/deployment-limits.md

@@ -0,0 +1,87 @@
+---
+title: Deployment — OS limits for multi-tenant pools
+slug: cor/deployment-limits
+public: true
+category: cor
+template: guide
+order: 6
+description: The two OS limits a per-tenant brain pool needs (open files + mmap regions), what cor sets automatically, what the deployment must set, and copy-paste Docker / Compose / Kubernetes / host config.
+---
+
+# Deployment — OS limits for multi-tenant pools
+
+Running **one brain per user** (e.g. Workshop) puts many isolated brains in one process. Each is lean — a few open files + a few mmap regions — but they add up. Two OS limits can bottleneck a pool **before RAM does**:
+
+| Limit | What it caps | Default (Linux) | Who sets it |
+|---|---|---|---|
+| `RLIMIT_NOFILE` (`ulimit -n`) | open files / process | soft **1024**, hard higher | **soft: cor (auto)** · hard: deployment |
+| `vm.max_map_count` | mmap regions / process (Linux-only) | **65530** | **deployment only** (global sysctl) |
+
+A single big brain (e.g. Venue) doesn't need these raised. They matter at **pool scale** (hundreds–thousands of brains in one process).
+
+## What cor does automatically
+
+- **Raises its own soft `nofile` limit toward the hard cap on startup** — no privilege needed, safe, zero-config (`native/src/resource_limits.rs`). So you only ever need to manage the **hard** cap.
+- **Warns once at pool scale** if the hard cap or `vm.max_map_count` is below the projected need, with the exact fix command (so a missing setting is never silent). Single-brain deployments stay quiet.
+- **`getOpenFileLimitInfo()`** exposes the live numbers for health checks / dashboards.
+
+A process **cannot** raise its hard `nofile` cap or `vm.max_map_count` — those are the two things the deployment must set.
+
+## Recommended values
+
+Per brain, post-lazy-shard: ~10–16 open files + ~24 mmap regions (with margin). For headroom to thousands of pooled brains:
+
+```
+ulimit -n        = 65536      (hard; cor raises soft to match)
+vm.max_map_count = 262144
+```
+
+## Copy-paste config
+
+**Docker (Workshop runs on Docker/GCE):**
+```bash
+docker run \
+  --ulimit nofile=65536:65536 \
+  --sysctl vm.max_map_count=262144 \
+  …your-image
+```
+
+**Docker Compose:**
+```yaml
+services:
+  workshop:
+    ulimits:
+      nofile: { soft: 65536, hard: 65536 }
+    sysctls:
+      vm.max_map_count: 262144
+```
+
+**Kubernetes** (`vm.max_map_count` is a *non-namespaced* sysctl on most clusters → set it on the node, e.g. via a privileged initContainer or node tuning; `nofile` via the runtime):
+```yaml
+# Node-level (initContainer or DaemonSet):
+#   sysctl -w vm.max_map_count=262144
+# Pod:
+spec:
+  containers:
+    - name: workshop
+      # container runtime nofile via securityContext / runtime config
+```
+
+**Bare GCE / host (persistent):**
+```bash
+# /etc/sysctl.d/99-cor.conf
+echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/99-cor.conf
+sudo sysctl --system
+# /etc/security/limits.d/99-cor.conf
+echo '* hard nofile 65536' | sudo tee /etc/security/limits.d/99-cor.conf
+```
+
+## Verify
+
+```bash
+ulimit -Hn                      # hard open-file cap
+cat /proc/sys/vm/max_map_count  # mmap region cap
+```
+Cor logs both at pool scale if they're low. If you see the warning, apply the config above and restart.
+
+> **Note:** `vm.max_map_count` is Linux-only. On a macOS dev laptop it doesn't exist (and rarely matters at dev scale); `ulimit -n` applies on both. Production (Linux/Docker/GCE) needs both.

package/docs/diskann.md

@@ -0,0 +1,184 @@
+---
+title: Adaptive DiskANN — From Laptop to Billion-Scale
+slug: cor/diskann
+public: true
+category: cor
+template: guide
+order: 3
+description: Cor's 100% pure-Rust Adaptive DiskANN. Vamana α-pruned graph + Product Quantization. MEASURED at 1 M (p50 0.85 ms, p99 5.23 ms) on bxl9000; PROJECTED to 1 B at 5–10 ms via mode-adaptive residency. Auto-engages on local storage; full migration path from existing HNSW.
+next:
+  - cor/scaling
+  - cor/performance
+  - cor/comparison
+---
+
+# Adaptive DiskANN — From Laptop to Billion-Scale
+
+Cor ships a **100% pure-Rust Adaptive DiskANN** implementation that takes a single Brainy instance from the ~10 M-vector HNSW comfort zone to **1 B+ vectors on commodity hardware**. MEASURED at 1 M: **p50 0.85 ms / p99 5.23 ms** on bxl9000 (mode=auto, in-memory). 1 B target is PROJECTED at ~5–10 ms via Mode 3 (on-disk) — the DiskANN paper's published range. It's an algorithmic alternative to HNSW, not a competitor service — it lives in the same plugin, behind the same Brainy APIs.
+
+**The "Adaptive" part:** the same on-disk index file silently changes residency mode based on dataset size + available RAM:
+
+| Mode | When auto-selects | What changes |
+|---|---|---|
+| **Mode 1 — in-memory** | Vectors × dim × 4 fits in RAM (typical up through 10 M at 128-dim, 1 M at 1536-dim) | Zero PQ compression. Full Vamana graph + vectors mmap'd into RAM. **Fastest** — no disk I/O on hot path. |
+| **Mode 2 — hybrid** | RAM-constrained but PQ centroids fit (100 M tier on commodity boxes) | PQ-compressed centroids in RAM (16–32× smaller); full vectors mmap'd from disk with page-cache promotion. ~2-3× slower than Mode 1. |
+| **Mode 3 — on-disk** | Billion-scale where even uncompressed vectors don't fit on commodity hardware | Maximally PQ-compressed; search walks disk via OS page cache + DiskANN's neighbour-prefetch pattern. Published 5 ms range from the paper. |
+
+You build the index once with cor 3.0 defaults; as your dataset grows over time, the same file changes its residency mode under the hood. No re-index, no API change, no perf cliff at boundaries.
+
+## The problem DiskANN solves
+
+HNSW is excellent up to roughly 10 M vectors per machine. Beyond that, two costs compound:
+
+1. **Memory pressure.** At 1 B vectors of 384-dim float32, the vectors alone are ~1.5 TB and the HNSW graph metadata adds another ~2 TB. Even with the cortex 2.4.0 mmap vector backend, the graph traversal pattern faults pages with no spatial locality.
+2. **No locality.** HNSW's insertion order has no correlation with traversal order on disk, so every search hop on a cold cache is a fresh ~10 μs page fault.
+
+DiskANN (Subramanya et al., NeurIPS 2019) was designed for exactly this regime:
+
+- **Vamana α-pruned graph** picks neighbours so that nodes visited together during search end up adjacent on disk — disk locality emerges from construction.
+- **Product Quantization** compresses each vector to M ≤ 16 bytes resident in RAM. At 1 B vectors that's ~16 GB of PQ codes instead of 1.5 TB of full vectors.
+- **Full vectors on disk** are only touched to re-rank the top candidate set, not during the graph walk.
+
+## What cor delivers
+
+- **One contiguous file** (header + codebook + PQ codes + Vamana graph + full vectors), mmap-mappable so an SSD-resident billion-vector dataset never has to be copied into RAM.
+- **Zero-copy section accessors** (`vectors_f32()` returns `&[f32]` directly into the mapped region).
+- **Parallel build** with rayon. The graph and PQ encoding both parallelize.
+- **File-backed build adjacency** for billion-scale construction (the in-RAM concurrent adjacency would consume ~64 GB of bookkeeping at 1 B nodes; the mmap variant uses atomic-u32 slots with sharded write locks).
+- **Connectivity-repair pass** that guarantees every node is reachable from the entry point. Sequential Vamana provides this via insertion order; parallel Vamana doesn't, so cor closes the gap explicitly.
+- **PQ-walk + full-vector re-rank** search. Greedy walk uses ADC distance over RAM-resident PQ codes (M-byte table lookups, ~50 ns per hop); re-rank then scores the **full walked candidate list** (the ~`l_search` visited set) with the exact full-precision distance — the mmap-resident vectors make that near-free, and it recovers true neighbours that PQ ranked below `k`. `l_search` is the recall dial; an optional `paddingFactor` can cap the re-rank to `ceil(k × paddingFactor)` to bound I/O on cold-NVMe billion-scale indexes.
+- **HNSW-shaped TS wrapper** (`NativeDiskAnnWrapper`) so Brainy's higher layers don't know which engine is underneath.
+
+## Scale envelope
+
+> **MEASURED at 1 M on bxl9000** (Ryzen 9 7950X3D / 184 GB / NVMe), reproducible via `scripts/verify-diskann.mjs`. SIFT1M canonical: **p50 0.86 ms / p99 1.22 ms, recall 0.9942** on the BIGANN reference dataset. 10 M / 100 M numbers below are partial-measured (SIFT10M canonical at p50 0.78 ms / p99 1.13 ms, hybrid mode). 1 B numbers are PROJECTED from the SIFT1B reference run + Subramanya et al. algorithm model.
+
+| Vectors | RAM with DiskANN | RAM with HNSW | Mode | DiskANN search latency |
+|--------:|---:|---:|---:|---:|
+| 1 M | 0.5–2 GB | 0.5–2 GB | Mode 1 | **p50 0.85 ms / p99 5.23 ms (MEASURED, mode=auto)** |
+| 10 M | 1–5 GB | 8–20 GB | Mode 1 | **p50 0.78 ms / p99 1.13 ms (MEASURED on SIFT10M, hybrid)** |
+| 100 M | 5–20 GB | 80–200 GB (impractical on single machine) | Mode 2 | 2–5 ms (PROJECTED from SIFT trends) |
+| 1 B | 20–70 GB | 1.5+ TB (single-machine impossible) | Mode 3 | 5–10 ms (PROJECTED from SIFT1B trends) |
+
+**End-to-end query latency at 1 B includes filesystem hydration of the returned entities.** Design target is ~100–500 ms total (dominated by the FileSystemStorage random reads + metadata lookup, PROJECTED). The roadmap to bring end-to-end query latency down to match search latency is in [`docs/scaling.md`](./scaling.md#operational-ceiling-at-1-b) — all fixes ship inside cor, no external storage.
+
+## How it engages
+
+Cor registers a `'diskann'` provider; Brainy's `createIndex()` consults it at init:
+
+1. **Explicit opt-in** via `config.index.type: 'diskann'` — required if the engagement conditions aren't satisfied, otherwise throws.
+2. **Auto-engagement** when all of:
+   - The cor DiskANN provider is registered (you've loaded the plugin).
+   - The storage adapter exposes a local filesystem path (`getBinaryBlobPath('_diskann/main')`). Cloud-storage adapters return `null` here and stay on HNSW.
+   - The metadata index has a stable `idMapper` (cortex 2.4.0's stable EntityIdMapper).
+3. **Explicit opt-out** via `config.index.type: 'hnsw'` keeps the historical in-memory index for the rare workload where you want it.
+
+```typescript
+import { BrainyData } from '@soulcraft/brainy'
+import { register as registerCor } from '@soulcraft/cor'
+
+const brain = new BrainyData({
+  storage: { type: 'filesystem', path: '/data/idx' }
+})
+await registerCor(brain)
+await brain.init()
+// → [brainy] DiskANN engaged (path=/data/idx/_diskann/main.bin, dim=384)
+
+const hits = await brain.search(queryVector, 10)
+// MEASURED at 1 M: p50 0.85 ms / p99 5.23 ms (mode=auto on bxl9000)
+// PROJECTED at 1 B: ~5–10 ms depending on cache state and SSD
+```
+
+All Brainy APIs — `add`, `search`, `relate`, `searchSimilarVerbs`, `find` — work unchanged.
+
+## Migrating an existing index
+
+Existing HNSW-backed Brainy installs **do not auto-migrate** on upgrade. They keep working as-is. To convert:
+
+```typescript
+const result = await brain.migrateToDiskAnn({
+  recallTarget: 0.95,    // require ≥95% recall vs old index before swapping
+  paddingFactor: 1.2,    // search-time over-fetch for re-rank
+  verifySampleSize: 100  // sample queries for the recall check
+})
+// 1. Builds new index in parallel (old HNSW keeps serving)
+// 2. Samples queries — compares top-k results between old and new
+// 3. Aborts if recall < target; old index stays in place
+// 4. Atomically swaps if recall passes
+
+// Reversible:
+await brain.migrateToHnsw()
+```
+
+Reversibility is a contract — production rollbacks are always available.
+
+## Tuning
+
+Defaults match the published DiskANN paper and work well for sentence/image embedding workloads (dim 128–1024). Tune via `config.index.diskann`:
+
+```typescript
+config.index.diskann = {
+  pqM: 16,                  // PQ subspaces; dim must be divisible by m
+  pqKsub: 256,              // centroids per subspace (8-bit codes — standard)
+  maxDegree: 64,            // Vamana R (out-degree per node)
+  searchListSize: 100,      // Vamana L (build-time candidate set)
+  alpha: 1.2,               // α-pruning density factor
+  useMmapAdjacency: true,   // file-backed build adjacency — REQUIRED at >100M nodes
+  mmapAdjacencyPath: '/data/scratch/diskann-build.adj'
+}
+```
+
+**At 1 B nodes you must set `useMmapAdjacency: true`.** The in-RAM concurrent adjacency would consume ~64 GB of bookkeeping at that scale — the mmap variant uses atomic-u32 slots with sharded write locks and bounded RAM (a few hundred mutexes for the shard table).
+
+## Dynamic writes
+
+DiskANN graphs are build-once by design. The cor wrapper handles dynamic writes via a delta buffer pattern that mirrors FreshDiskANN (Singh et al., 2021):
+
+- `addItem` → appends to an in-memory delta map.
+- `search` → queries the main index AND brute-forces the delta, merges, returns top-k.
+- `removeItem` → tombstone bitmap, filtered out at search time.
+- `rebuild()` → folds the delta into a new main index, swaps atomically.
+
+Operationally: insertions are O(1), reads stay sub-ms while delta fits in cache, and you schedule `rebuild()` during off-peak windows. The delta brute-force scales linearly in delta size; you keep it small.
+
+## On-disk format
+
+Single contiguous `main.bin`, all little-endian:
+
+```
++--------------------------------------------------------------+
+| Header (4 KB, page-aligned)                                  |
+|   magic="DKAN" · version · dim · node_count                  |
+|   pq_m · pq_ksub · pq_dsub · max_degree · entry_point        |
++--------------------------------------------------------------+
+| PQ codebook    (m × ksub × dsub × f32)                       |
++--------------------------------------------------------------+
+| PQ codes       (node_count × m bytes)                        |
++--------------------------------------------------------------+
+| Vamana graph   (node_count × max_degree × u32)               |
+|   Fixed-degree CSR. Sentinel `u32::MAX` marks unused slots.  |
++--------------------------------------------------------------+
+| Full vectors   (node_count × dim × f32)                      |
++--------------------------------------------------------------+
+```
+
+Fixed-degree adjacency means neighbour-offset math is O(1) — at search time `graph[node]` is a single seek to `graph_offset + node * max_degree * 4`. The mmap base is page-aligned by the OS and section offsets are 4-byte aligned by construction, so `bytemuck::cast_slice` reinterprets section bytes as `&[f32]` / `&[u32]` without copying.
+
+The same layout is what the build writes and the searcher mmaps — no separate serialization step.
+
+## Why 100% Rust, no C++ FFI
+
+Cor re-implements Vamana from the published paper rather than wrapping Microsoft's C++ reference. Reasons:
+
+1. **Cross-platform builds** for Node native modules become operationally expensive with C++ (Linux/macOS/Windows × x64/arm64 binaries, headers, link-time gotchas). napi-rs gives mature cross-platform binary distribution.
+2. **License posture** stays clean — pure Rust port from a published algorithm + permissive Rust deps (`memmap2`, `bytemuck`, `rayon`, `rand`, `thiserror`). No patent grant ambiguity.
+3. **Full control over the on-disk format** + napi bindings + future cor-specific optimizations.
+
+The pure-Rust DiskANN crate (`native/diskann/`) compiles and tests independently of napi, so it's separately benchmarkable and fuzz-target-ready.
+
+## See also
+
+- [ADR-002](./ADR-002-diskann.md) — the architectural decision record with full design rationale
+- [Scaling & Resource Management](./scaling.md) — multi-tenant density + the 1 B operational ceiling
+- [Performance benchmarks](./performance.md) — measured numbers from the included benchmark suite
+- [Brainy vs Brainy + Cor comparison](./comparison.md) — side-by-side feature and speed comparison