Replace method_references HashMap with SortedVecMap

Method references (8.96M entries) are bulk-loaded during indexing, never
accessed during resolution, and only queried/removed during incremental
updates and FFI queries. This access pattern is ideal for a sorted Vec:

- HashMap: ~16M slots × 41 bytes = ~656 MB (load factor + control bytes)
- SortedVec: 8.96M × 40 bytes = ~342 MB (no overhead)

Introduces SortedVecMap<K, V> backed by a sorted Vec<(K, V)> with O(log n)
binary search lookups. Uses UnsafeCell for lazy sorting so get() can take
&self. Entries are bulk-pushed unsorted during indexing, then sorted lazily
on first lookup.

## Benchmark (cumulative with NonZeroU64 change)

| Metric | Before | After | Delta |
|--------|--------|-------|-------|
| Memory (peak footprint) | 4480 MB | 3542 MB | -20.9% |
| Declarations | 895,844 | 895,844 | identical |
| Definitions | 1,063,171 | 1,063,171 | identical |

Author: st0012

rust/rubydex/src/main.rs

@@ -86,6 +86,9 @@ fn main() {
         eprintln!("{error}");
     }
 
+    // Sort method references after bulk loading for efficient lookup
+    graph.sort_method_references();
+
     if let Some(StopAfter::Indexing) = args.stop_after {
         return exit(args.stats);
     }

rust/rubydex/src/model.rs

@@ -9,5 +9,6 @@ pub mod identity_maps;
 pub mod ids;
 pub mod name;
 pub mod references;
+pub mod sorted_vec_map;
 pub mod string_ref;
 pub mod visibility;

rust/rubydex/src/model/graph.rs

@@ -11,6 +11,7 @@ use crate::model::identity_maps::{IdentityHashMap, IdentityHashSet};
 use crate::model::ids::{DeclarationId, DefinitionId, NameId, ReferenceId, StringId, UriId};
 use crate::model::name::{Name, NameRef, ParentScope, ResolvedName};
 use crate::model::references::{ConstantReference, MethodRef};
+use crate::model::sorted_vec_map::SortedVecMap;
 use crate::model::string_ref::StringRef;
 use crate::stats;
 
@@ -48,8 +49,9 @@ pub struct Graph {
     names: IdentityHashMap<NameId, NameRef>,
     // Map of constant references
     constant_references: IdentityHashMap<ReferenceId, ConstantReference>,
-    // Map of method references that still need to be resolved
-    method_references: IdentityHashMap<ReferenceId, MethodRef>,
+    // Method references stored as a sorted vec for compact memory usage.
+    // Not used during resolution — only queried and removed during incremental updates.
+    method_references: SortedVecMap<ReferenceId, MethodRef>,
 
     /// The position encoding used for LSP line/column locations. Not related to the actual encoding of the file
     position_encoding: Encoding,
@@ -69,7 +71,7 @@ impl Graph {
             strings: IdentityHashMap::default(),
             names: IdentityHashMap::default(),
             constant_references: IdentityHashMap::default(),
-            method_references: IdentityHashMap::default(),
+            method_references: SortedVecMap::new(),
             position_encoding: Encoding::default(),
             name_dependents: IdentityHashMap::default(),
         }
@@ -358,12 +360,18 @@ impl Graph {
         &self.constant_references
     }
 
-    // Returns an immutable reference to the method references map
+    // Returns an immutable reference to the method references
     #[must_use]
-    pub fn method_references(&self) -> &IdentityHashMap<ReferenceId, MethodRef> {
+    pub fn method_references(&self) -> &SortedVecMap<ReferenceId, MethodRef> {
         &self.method_references
     }
 
+    /// Sort method references for efficient lookup.
+    /// Must be called after bulk loading (indexing) is complete.
+    pub fn sort_method_references(&mut self) {
+        self.method_references.sort();
+    }
+
     #[must_use]
     pub fn all_diagnostics(&self) -> Vec<&Diagnostic> {
         let document_diagnostics = self.documents.values().flat_map(Document::all_diagnostics);
@@ -776,9 +784,7 @@ impl Graph {
         }
 
         for (method_ref_id, method_ref) in method_references {
-            if self.method_references.insert(method_ref_id, method_ref).is_some() {
-                debug_assert!(false, "Method ReferenceId collision in global graph");
-            }
+            self.method_references.push(method_ref_id, method_ref);
         }
 
         for (name_id, deps) in name_dependents {
@@ -945,6 +951,7 @@ impl Graph {
         &self.position_encoding
     }
 
+
     #[allow(clippy::cast_precision_loss)]
     pub fn print_query_statistics(&self) {
         use std::collections::{HashMap, HashSet};

rust/rubydex/src/model/sorted_vec_map.rs

@@ -0,0 +1,154 @@
+use std::cell::UnsafeCell;
+
+/// A sorted Vec-based map for compact storage of bulk-loaded key-value pairs.
+///
+/// Uses a flat `Vec<(K, V)>` sorted by key for O(log n) lookups.
+/// Much more memory-efficient than HashMap for large collections that are
+/// bulk-loaded then mostly read, with occasional removals.
+///
+/// # When to use
+///
+/// Use this instead of HashMap when **all** of the following are true:
+/// - The collection is large (millions of entries) — small maps don't benefit
+/// - Entries are bulk-loaded (e.g., during indexing), not inserted one-at-a-time in hot loops
+/// - Lookups are infrequent or off the critical path (O(log n) binary search, not O(1))
+///
+/// **Do not use** for collections accessed in tight loops during resolution or
+/// other hot paths. Binary search on large arrays causes cache misses that
+/// make it slower than HashMap despite the memory savings. For example,
+/// `constant_references` (5.64M entries, queried millions of times during
+/// resolution) showed a 24% time regression when switched to SortedVecMap.
+///
+/// # Implementation
+///
+/// Uses interior mutability for lazy sorting: `get()` takes `&self` and sorts
+/// on first access if needed. This is safe because sorting is idempotent and
+/// the map is only accessed from a single thread at a time.
+pub struct SortedVecMap<K, V> {
+    // UnsafeCell allows mutation through &self for lazy sorting.
+    // Safety: rubydex's Graph is single-threaded for mutations.
+    inner: UnsafeCell<SortedVecMapInner<K, V>>,
+}
+
+struct SortedVecMapInner<K, V> {
+    entries: Vec<(K, V)>,
+    sorted: bool,
+}
+
+// SAFETY: SortedVecMap is only used within Graph which is single-threaded for mutations.
+// The UnsafeCell is only mutated during lazy sorting which is idempotent.
+// Sync is needed because Graph is stored in Arc<Mutex<>> in the MCP server.
+unsafe impl<K: Send, V: Send> Send for SortedVecMap<K, V> {}
+unsafe impl<K: Send + Sync, V: Send + Sync> Sync for SortedVecMap<K, V> {}
+
+impl<K: std::fmt::Debug, V: std::fmt::Debug> std::fmt::Debug for SortedVecMap<K, V> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let inner = unsafe { &*self.inner.get() };
+        f.debug_struct("SortedVecMap")
+            .field("entries", &inner.entries)
+            .field("sorted", &inner.sorted)
+            .finish()
+    }
+}
+
+impl<K, V> Default for SortedVecMap<K, V> {
+    fn default() -> Self {
+        Self {
+            inner: UnsafeCell::new(SortedVecMapInner {
+                entries: Vec::new(),
+                sorted: true,
+            }),
+        }
+    }
+}
+
+impl<K: Ord + Copy, V> SortedVecMap<K, V> {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Ensure the entries are sorted.
+    fn ensure_sorted(&self) {
+        let inner = unsafe { &mut *self.inner.get() };
+        if !inner.sorted {
+            inner.entries.sort_unstable_by_key(|(k, _)| *k);
+            inner.sorted = true;
+        }
+    }
+
+    fn inner(&self) -> &SortedVecMapInner<K, V> {
+        unsafe { &*self.inner.get() }
+    }
+
+    /// Push a new entry without maintaining sort order.
+    pub fn push(&mut self, key: K, value: V) {
+        let inner = self.inner.get_mut();
+        inner.entries.push((key, value));
+        inner.sorted = false;
+    }
+
+    /// Insert a key-value pair, returning the previous value if the key already existed.
+    pub fn insert(&mut self, key: K, value: V) -> Option<V> {
+        self.ensure_sorted();
+        let inner = self.inner.get_mut();
+        match inner.entries.binary_search_by_key(&key, |(k, _)| *k) {
+            Ok(index) => {
+                let old = std::mem::replace(&mut inner.entries[index].1, value);
+                Some(old)
+            }
+            Err(index) => {
+                inner.entries.insert(index, (key, value));
+                None
+            }
+        }
+    }
+
+    /// Look up a value by key. Lazily sorts if needed.
+    pub fn get(&self, key: &K) -> Option<&V> {
+        self.ensure_sorted();
+        let inner = self.inner();
+        inner.entries
+            .binary_search_by_key(key, |(k, _)| *k)
+            .ok()
+            .map(|index| &inner.entries[index].1)
+    }
+
+    /// Remove an entry by key, returning the value if found.
+    pub fn remove(&mut self, key: &K) -> Option<V> {
+        self.ensure_sorted();
+        let inner = self.inner.get_mut();
+        match inner.entries.binary_search_by_key(key, |(k, _)| *k) {
+            Ok(index) => Some(inner.entries.remove(index).1),
+            Err(_) => None,
+        }
+    }
+
+    pub fn len(&self) -> usize {
+        self.inner().entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.inner().entries.is_empty()
+    }
+
+    pub fn keys(&self) -> impl Iterator<Item = &K> {
+        self.inner().entries.iter().map(|(k, _)| k)
+    }
+
+    pub fn values(&self) -> impl Iterator<Item = &V> {
+        self.inner().entries.iter().map(|(_, v)| v)
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = (&K, &V)> {
+        self.inner().entries.iter().map(|(k, v)| (k, v))
+    }
+
+    pub fn shrink_to_fit(&mut self) {
+        self.inner.get_mut().entries.shrink_to_fit();
+    }
+
+    /// Sort the map if not already sorted.
+    pub fn sort(&mut self) {
+        self.ensure_sorted();
+    }
+}