perf(builtin): probe Map with unchecked array access

Every probe index in `Map` comes from `hash & capacity_mask` and is
re-masked as `(idx + 1) & capacity_mask` on each step, so it is always in
bounds for `entries`, whose length is `capacity`. The bounds check on
those accesses is provably redundant.

Convert the 18 masked-probe sites to `unsafe_get` / `unsafe_set`, with
the invariant stated once at the top of the file and a marker at each
loop head.

`Map` is a linked hash map, so unlike `hashset` and `hashmap` it also
stores slot indices in the list itself -- `prev`, `tail`, and the index
`retain` destructures out of an entry. Every access through one of those
keeps the checked form. Such indices are in bounds too, being former
probe indices in a table that never shrinks, but that argument rests on
the list being maintained correctly rather than on arithmetic alone, and
that is not a foundation to put unchecked access on.

`shift_back` is the deliberate exception. It is reachable from `retain`
with a stored index, but `retain` performs its own checked read
immediately before calling, so `shift_back` has a local caller-based
proof that does not depend on the list invariant at all. It carries that
proof at its definition, and that proof is also what makes the
`set_entry` call inside it sound.

Also adds `builtin/linked_hash_map_bench_test.mbt`, covering insertion,
hits, misses, set+remove, and insertion-ordered iteration.

Measured against `main`, n=50000, interleaved in one session:

| backend | op | main | this | change |
| ------- | -- | ---- | ---- | ------ |
| js      | `set`        | 3.97 ms | 3.14 ms | 21% faster |
| js      | `get` hit    | 1.30 ms | 1.02 ms | 22% faster |
| js      | `get` miss   | 1.37 ms | 1.17 ms | 15% faster |
| js      | `set+remove` | 5.70 ms | 4.54 ms | 20% faster |
| native  | all          |         |         | within noise |
| wasm-gc | all          |         |         | within noise |

This is the largest js gain of the four hash containers, and the reason
is load factor rather than anything about `Map` itself: at 50000 entries
`Map` sits at roughly 76% of 65536 slots while `HashMap` sits at roughly
38% of 131072, so `Map` probes more per operation and therefore has more
checks to remove. `HashSet`, at a similar load, gains similarly. The
percentages are empirical -- js randomises its hash seed, so they will
move between runs.

`each` is unchanged by design, since it walks the list rather than the
table.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: bobzhang

builtin/linked_hash_map.mbt

@@ -51,6 +51,29 @@ struct Map[K, V] {
 
 // Implementations
 
+// SAFETY NOTE for the unchecked probe accesses in this file.
+//
+// `capacity` is always a power of two and at least 1, `capacity_mask` is
+// `capacity - 1`, and `entries.length()` is `capacity`. A probe index is
+// therefore always in bounds: it starts as `hash & capacity_mask` and each
+// step re-masks with `(idx + 1) & capacity_mask`. `grow` installs the new
+// array, capacity and mask together before any rehash probe runs, and
+// `set_with_hash` re-masks from scratch after growing.
+//
+// Only those probe indices use `unsafe_get` / `unsafe_set`. `Map` also
+// stores slot indices in the list itself -- `prev`, `tail`, and the index
+// `retain` destructures out of an entry -- and every access through one of
+// those keeps the checked form. They are in bounds too, being former probe
+// indices in a table that never shrinks, but that argument depends on the
+// list being maintained correctly rather than on arithmetic alone, so it is
+// not one to build unchecked access on.
+//
+// `shift_back` is the exception, and deliberately so: it is reachable from
+// `retain` with a stored index, but `retain` performs its own checked read
+// immediately before calling, so `shift_back` has a local caller-based proof
+// that does not depend on the list invariant. It carries that proof at its
+// definition, and it is what makes its `set_entry` call sound.
+
 ///|
 let default_init_capacity = 8
 
@@ -140,8 +163,9 @@ fn[K : Eq, V] Map::set_with_hash(
   hash : Int,
 ) -> Unit {
   // Only grow when actually inserting a new entry, not when updating existing
+  // SAFETY: masked probe index; see the note at the top of this file.
   for psl = 0, idx = hash & self.capacity_mask {
-    match self.entries[idx] {
+    match self.entries.unsafe_get(idx) {
       None => {
         // Need to insert new entry - check if grow is needed first
         if self.size >= self.grow_at {
@@ -184,8 +208,9 @@ fn[K, V] Map::push_away(
   idx : Int,
   entry : Entry[K, V],
 ) -> Unit {
+  // SAFETY: masked probe index; see the note at the top of this file.
   for psl = entry.psl + 1, idx = (idx + 1) & self.capacity_mask, entry = entry {
-    match self.entries[idx] {
+    match self.entries.unsafe_get(idx) {
       None => {
         entry.psl = psl
         self.set_entry(entry, idx)
@@ -219,7 +244,7 @@ fn[K, V] Map::set_entry(
     None => self.tail = new_idx
     Some(next) => next.prev = new_idx
   }
-  self.entries[new_idx] = Some(entry)
+  self.entries.unsafe_set(new_idx, Some(entry))
 }
 
 ///|
@@ -243,8 +268,9 @@ fn[K, V] Map::set_entry(
 /// ```
 pub fn[K : Hash + Eq, V] Map::get(self : Map[K, V], key : K) -> V? {
   let hash = Hash::hash(key)
+  // SAFETY: masked probe index; see the note at the top of this file.
   for i = 0, idx = hash & self.capacity_mask {
-    guard self.entries[idx] is Some(entry) else { break None }
+    guard self.entries.unsafe_get(idx) is Some(entry) else { break None }
     if entry.hash == hash && entry.key == key {
       break Some(entry.value)
     }
@@ -260,8 +286,9 @@ pub fn[K : Hash + Eq, V] Map::get(self : Map[K, V], key : K) -> V? {
 #alias("_[_]")
 pub fn[K : Hash + Eq, V] Map::at(self : Map[K, V], key : K) -> V {
   let hash = Hash::hash(key)
+  // SAFETY: masked probe index; see the note at the top of this file.
   for i = 0, idx = hash & self.capacity_mask {
-    guard! self.entries[idx] is Some(entry)
+    guard! self.entries.unsafe_get(idx) is Some(entry)
     if entry.hash == hash && entry.key == key {
       return entry.value
     }
@@ -299,8 +326,9 @@ pub fn[K : Hash + Eq, V] Map::get_or_default(
   default : V,
 ) -> V {
   let hash = Hash::hash(key)
+  // SAFETY: masked probe index; see the note at the top of this file.
   for i = 0, idx = hash & self.capacity_mask {
-    match self.entries[idx] {
+    match self.entries.unsafe_get(idx) {
       Some(entry) => {
         if entry.hash == hash && entry.key == key {
           break entry.value
@@ -323,9 +351,10 @@ pub fn[K : Hash + Eq, V] Map::get_or_init(
   default : () -> V,
 ) -> V {
   let hash = Hash::hash(key)
+  // SAFETY: masked probe index; see the note at the top of this file.
   let (idx, psl, new_value, push_away) = for psl = 0, idx = hash &
                                                self.capacity_mask {
-    match self.entries[idx] {
+    match self.entries.unsafe_get(idx) {
       Some(entry) => {
         if entry.hash == hash && entry.key == key {
           return entry.value
@@ -389,8 +418,9 @@ pub fn[K : Hash + Eq, V] Map::update_or_default(
   f : (V) -> V,
 ) -> Unit {
   let hash = Hash::hash(key)
+  // SAFETY: masked probe index; see the note at the top of this file.
   let (idx, psl, push_away) = for psl = 0, idx = hash & self.capacity_mask {
-    match self.entries[idx] {
+    match self.entries.unsafe_get(idx) {
       Some(entry) => {
         if entry.hash == hash && entry.key == key {
           entry.value = f(entry.value)
@@ -421,8 +451,9 @@ pub fn[K : Hash + Eq, V] Map::update_or_default(
 pub fn[K : Hash + Eq, V] Map::contains(self : Map[K, V], key : K) -> Bool {
   // inline Map::get to avoid boxing
   let hash = Hash::hash(key)
+  // SAFETY: masked probe index; see the note at the top of this file.
   for i = 0, idx = hash & self.capacity_mask {
-    guard self.entries[idx] is Some(entry) else { break false }
+    guard self.entries.unsafe_get(idx) is Some(entry) else { break false }
     if entry.hash == hash && entry.key == key {
       break true
     }
@@ -462,8 +493,9 @@ pub fn[K : Hash + Eq, V : Eq] Map::contains_kv(
 ) -> Bool {
   // inline Map::get to avoid boxing
   let hash = Hash::hash(key)
+  // SAFETY: masked probe index; see the note at the top of this file.
   for i = 0, idx = hash & self.capacity_mask {
-    guard self.entries[idx] is Some(entry) else { break false }
+    guard self.entries.unsafe_get(idx) is Some(entry) else { break false }
     if entry.hash == hash && entry.key == key && entry.value == value {
       break true
     }
@@ -505,8 +537,9 @@ fn[K : Eq, V] Map::remove_with_hash(
   key : K,
   hash : Int,
 ) -> Unit {
+  // SAFETY: masked probe index; see the note at the top of this file.
   for i = 0, idx = hash & self.capacity_mask {
-    guard self.entries[idx] is Some(entry) else { break }
+    guard self.entries.unsafe_get(idx) is Some(entry) else { break }
     if entry.hash == hash && entry.key == key {
       self.remove_entry(entry)
       self.shift_back(idx)
@@ -532,7 +565,7 @@ fn[K, V] Map::add_entry_to_tail(
     tail => self.entries[tail].unwrap().next = Some(entry)
   }
   self.tail = idx
-  self.entries[idx] = Some(entry)
+  self.entries.unsafe_set(idx, Some(entry))
   self.size += 1
 }
 
@@ -550,11 +583,17 @@ fn[K, V] Map::remove_entry(self : Map[K, V], entry : Entry[K, V]) -> Unit {
 
 ///|
 fn[K, V] Map::shift_back(self : Map[K, V], idx : Int) -> Unit {
+  // SAFETY: the initial `cur` is in bounds by every route its callers take,
+  // and none of them requires trusting the list invariant: `remove` and
+  // `update` pass a masked probe index, and `retain` performs its own
+  // checked `entries[idx]` read immediately before calling. `next` is
+  // re-masked each step and later `cur` values are previous `next` values.
+  // This is also what makes the `set_entry` call below sound.
   for cur = idx {
     let next = (cur + 1) & self.capacity_mask
-    match self.entries[next] {
+    match self.entries.unsafe_get(next) {
       None | Some({ psl: 0, .. }) => {
-        self.entries[cur] = None
+        self.entries.unsafe_set(cur, None)
         break
       }
       Some(entry) => {
@@ -594,8 +633,9 @@ fn[K, V] Map::grow(self : Map[K, V]) -> Unit {
 #owned(outer)
 fn[K, V] Map::rehash_place_entry(self : Map[K, V], outer : Entry[K, V]) -> Unit {
   let hash = outer.hash
+  // SAFETY: masked probe index; see the note at the top of this file.
   for psl = 0, idx = hash & self.capacity_mask {
-    match self.entries[idx] {
+    match self.entries.unsafe_get(idx) {
       None => {
         outer.psl = psl
         outer.prev = self.tail
@@ -1094,9 +1134,10 @@ pub fn[K : Hash + Eq, V] Map::update(
   f : (V?) -> V?,
 ) -> Unit {
   let hash = Hash::hash(key)
+  // SAFETY: masked probe index; see the note at the top of this file.
   let (idx, psl, new_value, push_away) = for psl = 0, idx = hash &
                                                self.capacity_mask {
-    match self.entries[idx] {
+    match self.entries.unsafe_get(idx) {
       Some(entry) => {
         if entry.hash == hash && entry.key == key {
           // Found the entry, update its value
@@ -1169,8 +1210,9 @@ pub fn[K : Hash + Eq, V] Map::update(
 /// ```
 pub fn[V] Map::get_from_bytes(map : Self[Bytes, V], key : BytesView) -> V? {
   let hash = key.hash()
+  // SAFETY: masked probe index; see the note at the top of this file.
   for i = 0, idx = hash & map.capacity_mask {
-    guard map.entries[idx] is Some(entry) else { break None }
+    guard map.entries.unsafe_get(idx) is Some(entry) else { break None }
     if entry.hash == hash && key.equal_to_bytes(entry.key) {
       break Some(entry.value)
     }
@@ -1206,8 +1248,9 @@ pub fn[V] Map::get_from_bytes(map : Self[Bytes, V], key : BytesView) -> V? {
 /// ```
 pub fn[V] Map::get_from_string(map : Self[String, V], key : StringView) -> V? {
   let hash = key.hash()
+  // SAFETY: masked probe index; see the note at the top of this file.
   for i = 0, idx = hash & map.capacity_mask {
-    guard map.entries[idx] is Some(entry) else { break None }
+    guard map.entries.unsafe_get(idx) is Some(entry) else { break None }
     if entry.hash == hash && key.equal_to_string(entry.key) {
       break Some(entry.value)
     }

builtin/linked_hash_map_bench_test.mbt

@@ -0,0 +1,93 @@
+// Copyright 2026 International Digital Economy Academy
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+///|
+let map_bench_n = 50000
+
+///|
+test "bench Map::set n=50000" (it : @bench.T) {
+  it.bench(fn() {
+    let m : Map[Int, Int] = Map([])
+    for i in 0..<map_bench_n {
+      m.set(i * 1103515245, i)
+    }
+    it.keep(m.length())
+  })
+}
+
+///|
+test "bench Map::get n=50000" (it : @bench.T) {
+  let m : Map[Int, Int] = Map([])
+  for i in 0..<map_bench_n {
+    m.set(i * 1103515245, i)
+  }
+  it.bench(fn() {
+    let mut hits = 0
+    for i in 0..<map_bench_n {
+      if m.get(i * 1103515245) is Some(_) {
+        hits += 1
+      }
+    }
+    it.keep(hits)
+  })
+}
+
+///|
+test "bench Map::get miss n=50000" (it : @bench.T) {
+  let m : Map[Int, Int] = Map([])
+  for i in 0..<map_bench_n {
+    m.set(i * 1103515245, i)
+  }
+  it.bench(fn() {
+    let mut misses = 0
+    for i in 0..<map_bench_n {
+      if m.get(i * 1103515245 + 1) is None {
+        misses += 1
+      }
+    }
+    it.keep(misses)
+  })
+}
+
+///|
+/// Named for what it measures: `@bench.T` has no per-iteration setup hook,
+/// so the map has to be rebuilt inside the timed closure and the removal
+/// cost cannot be isolated from the insertion cost.
+test "bench Map::set+remove n=50000" (it : @bench.T) {
+  it.bench(fn() {
+    let m : Map[Int, Int] = Map([])
+    for i in 0..<map_bench_n {
+      m.set(i * 1103515245, i)
+    }
+    for i in 0..<map_bench_n {
+      m.remove(i * 1103515245)
+    }
+    it.keep(m.length())
+  })
+}
+
+///|
+/// Insertion-ordered iteration, which is the reason `Map` keeps a list at
+/// all, so it is worth guarding against regressions here.
+test "bench Map::each n=50000" (it : @bench.T) {
+  let m : Map[Int, Int] = Map([])
+  for i in 0..<map_bench_n {
+    m.set(i * 1103515245, i)
+  }
+  it.bench(fn() {
+    let mut total = 0
+    m.each((_, v) => total = total + v)
+    it.keep(total)
+  })
+}