reg-vm: support struct/list/option-typed Map and Set keys

The register VM only accepted Bool/Int/String map keys (VmMapKey was a
three-variant enum), so a `derives(Eq, Hash)` struct/sum used as a `Map` key or
`Set` element - which the compiled backend keys on directly - failed at runtime
with "reg VM Map key does not support ...". That was a real VM/compiled
capability divergence (surfaced by the example-corpus differential on
uop_interning.rss).

Make VmMapKey wrap any hashable VmValue:
 - equality reuses VmValue's existing structural PartialEq;
 - Hash is a matching recursive projection (hash_vm_value) so equal keys hash
   equal - covering scalars, String/Bytes/Char/Unit, the structural
   List/Deque/Option containers, and struct/variant fields, with Managed
   unwrapped transparently (consistent with Eq) and +-0.0 normalized.
map_key_from_value now accepts the full hashable shape and rejects only the
genuinely unhashable values (Float/Map/Json/Closure) with the same clean error;
vm_value_from_map_key (used by Map.keys/Set.to_list) just clones the stored
value, so keys round-trip exactly with no struct reconstruction.

Keys remain Rc-shared rather than deep-copied: Map.insert/Set.insert declare
retains(key), so the move checker forbids mutating a key while it is in a map,
which is why the (now interior-mutable) VmMapKey is sound - documented at the
scoped clippy::mutable_key_type allows.

Tests: add backends_agree_on_struct_keyed_collections (struct key with nested
List/Option: dedup, lookup, Map.keys round-trip, Set membership - VM == JIT ==
compiled) and drop the now-unneeded uop_interning skip from the example sweep.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Haofei

crates/rsscript/src/reg_vm/mod.rs

@@ -6617,6 +6617,10 @@ impl RegVm {
     /// the interpreter (`drive`) and the JIT executor (`run_jit`), so the two can
     /// never silently diverge. Jumps update `*ip`; `Return` is handed back to the
     /// caller (which owns frame unwinding); everything else is [`PureStep::NotPure`].
+    // `VmMapKey` is interior-mutable (List/struct keys hold `Rc<RefCell<…>>`),
+    // but `Map.insert`'s `retains(key)` effect makes mutating a live key
+    // unreachable in well-typed RSScript, so the lint's hazard cannot occur.
+    #[allow(clippy::mutable_key_type)]
     fn try_exec_pure(
         &mut self,
         instr: &RegInstr,
@@ -8687,6 +8691,9 @@ impl RegVm {
         }
     }
 
+    // See `try_exec_pure`: interior-mutable `VmMapKey` is safe because
+    // `retains(key)` forbids mutating a key while it is in a map.
+    #[allow(clippy::mutable_key_type)]
     fn call_intrinsic(
         &mut self,
         unit: &RegUnit,
@@ -13080,23 +13087,43 @@ fn ensure_option_value(value: VmValue) -> Result<VmValue, EvalError> {
 }
 
 fn map_key_from_value(value: &VmValue) -> Result<VmMapKey, EvalError> {
-    match value {
-        VmValue::Bool(value) => Ok(VmMapKey::Bool(*value)),
-        VmValue::Int(value) => Ok(VmMapKey::Int(*value)),
-        VmValue::String(value) => Ok(VmMapKey::String(Rc::clone(value))),
-        other => Err(EvalError::Runtime(format!(
+    // The checker guarantees a key's static type is `Hashable`, so this is a
+    // defensive gate: it accepts every shape RSScript admits as a key — scalars,
+    // strings/bytes, the structural `List`/`Deque`/`Option` containers, and
+    // `derives(Eq, Hash)` structs/sums (recursively) — and rejects only the
+    // genuinely unhashable values (`Float`, `Map`, raw `Json`, closures) with a
+    // clean runtime error rather than a host panic.
+    fn is_hashable(value: &VmValue) -> bool {
+        match value {
+            VmValue::Unit
+            | VmValue::Bool(_)
+            | VmValue::Int(_)
+            | VmValue::Char(_)
+            | VmValue::String(_)
+            | VmValue::Bytes(_)
+            | VmValue::Native(_)
+            | VmValue::OptionNone => true,
+            VmValue::OptionSome(inner) => is_hashable(inner),
+            VmValue::List(items) => items.borrow().iter().all(is_hashable),
+            VmValue::Deque(items) => items.borrow().iter().all(is_hashable),
+            VmValue::Struct(data) | VmValue::Variant(data) => data.fields.iter().all(is_hashable),
+            VmValue::Managed(inner) => is_hashable(&inner.borrow()),
+            VmValue::Float(_) | VmValue::Map(_) | VmValue::Json(_) | VmValue::Closure(_) => false,
+        }
+    }
+
+    if is_hashable(value) {
+        Ok(VmMapKey::new(value.clone()))
+    } else {
+        Err(EvalError::Runtime(format!(
             "reg VM Map key does not support `{}`.",
-            other.display()
-        ))),
+            value.display()
+        )))
     }
 }
 
 fn vm_value_from_map_key(key: &VmMapKey) -> VmValue {
-    match key {
-        VmMapKey::Bool(value) => VmValue::Bool(*value),
-        VmMapKey::Int(value) => VmValue::Int(*value),
-        VmMapKey::String(value) => VmValue::String(Rc::clone(value)),
-    }
+    key.value().clone()
 }
 
 fn json_kind(value: &serde_json::Value) -> &'static str {

crates/rsscript/src/reg_vm/runtime_values.rs

@@ -263,6 +263,12 @@ pub(super) fn json_decode_struct_value(
     ))))
 }
 
+// `VmMapKey` wraps a `VmValue`, which has interior mutability (a `List`/struct
+// key holds `Rc<RefCell<…>>`). The `mutable_key_type` hazard — mutating a key
+// while it sits in a map — cannot occur in well-typed RSScript: `Map.insert`
+// declares `retains(key)`, so the move checker forbids mutating a key after
+// insertion. The hash projection reads the (immutable-by-contract) contents.
+#[allow(clippy::mutable_key_type)]
 pub(super) fn json_decode_field_value(
     unit: &RegUnit,
     type_name: &str,
@@ -334,7 +340,7 @@ pub(super) fn json_decode_field_value(
             let mut decoded = ValueMap::with_capacity_and_hasher(object.len(), Default::default());
             for (key, value) in object {
                 decoded.insert(
-                    VmMapKey::String(Rc::new(key.clone())),
+                    VmMapKey::from_string(key.clone()),
                     json_decode_field_value(unit, args[1], value)?,
                 );
             }

crates/rsscript/src/reg_vm/value_convert.rs

@@ -285,7 +285,7 @@ pub(super) fn vm_value_to_json_literal(value: &VmValue) -> Result<serde_json::Va
         VmValue::Map(entries) => {
             let mut object = serde_json::Map::new();
             for (key, value) in entries.borrow().iter() {
-                let VmMapKey::String(key) = key else {
+                let Some(key) = key.as_str() else {
                     return Err(EvalError::Runtime(format!(
                         "cannot convert map key `{}` to a JSON literal.",
                         key.display()
@@ -460,6 +460,10 @@ pub(super) fn unmanage_vm_value(value: VmValue) -> VmValue {
 /// reference type, so it keeps its handle (mirroring the backend, which shares
 /// `Managed` and treats plain collections as value types). Immutable handles
 /// (`String`/`Bytes`/`Json`) and opaque values are cloned shallowly.
+// See the note in `runtime_values::json_decode_field_value`: a `VmMapKey` is
+// interior-mutable but the `retains(key)` effect makes mutating a live key
+// unreachable in well-typed programs.
+#[allow(clippy::mutable_key_type)]
 pub(super) fn deep_copy_value(value: &VmValue) -> VmValue {
     match value {
         VmValue::List(items) => {
@@ -647,10 +651,10 @@ pub(super) fn vm_value_from_native_value(value: NativeValue) -> VmValue {
 
 pub(super) fn vm_map_key_from_native_value(value: NativeValue) -> VmMapKey {
     match value {
-        NativeValue::Bool(value) => VmMapKey::Bool(value),
-        NativeValue::Int(value) => VmMapKey::Int(value),
-        NativeValue::String(value) => VmMapKey::String(Rc::new(value)),
-        other => VmMapKey::String(Rc::new(format!("{other:?}"))),
+        NativeValue::Bool(value) => VmMapKey::new(VmValue::Bool(value)),
+        NativeValue::Int(value) => VmMapKey::new(VmValue::Int(value)),
+        NativeValue::String(value) => VmMapKey::from_string(value),
+        other => VmMapKey::from_string(format!("{other:?}")),
     }
 }
 
@@ -708,7 +712,7 @@ mod tests {
         );
 
         let mut map: ValueMap = ValueMap::default();
-        map.insert(VmMapKey::Int(1), VmValue::string("one"));
+        map.insert(VmMapKey::new(VmValue::Int(1)), VmValue::string("one"));
         assert_eq!(
             to_native(VmValue::Map(Rc::new(RefCell::new(map)))),
             NativeValue::Map(vec![(
@@ -861,20 +865,20 @@ mod tests {
     fn map_key_from_native_falls_back_to_string() {
         assert_eq!(
             vm_map_key_from_native_value(NativeValue::Bool(true)),
-            VmMapKey::Bool(true)
+            VmMapKey::new(VmValue::Bool(true))
         );
         assert_eq!(
             vm_map_key_from_native_value(NativeValue::Int(2)),
-            VmMapKey::Int(2)
+            VmMapKey::new(VmValue::Int(2))
         );
         assert_eq!(
             vm_map_key_from_native_value(NativeValue::String("k".to_string())),
-            VmMapKey::String(Rc::new("k".to_string()))
+            VmMapKey::from_string("k")
         );
         // A non-scalar key has no VM key form, so it falls back to its debug string.
-        match vm_map_key_from_native_value(NativeValue::Float(1.0)) {
-            VmMapKey::String(s) => assert!(s.contains("Float"), "{s}"),
-            other => panic!("expected string fallback, got {other:?}"),
+        match vm_map_key_from_native_value(NativeValue::Float(1.0)).as_str() {
+            Some(s) => assert!(s.contains("Float"), "{s}"),
+            None => panic!("expected string fallback"),
         }
     }
 }

crates/rsscript/src/vm_value.rs

@@ -168,28 +168,133 @@ pub(crate) struct VmNative {
     pub(crate) id: i64,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
-pub(crate) enum VmMapKey {
-    Bool(bool),
-    Int(i64),
-    String(Rc<String>),
-}
+/// A `Map`/`Set` key: any hashable `VmValue`. Keys are not restricted to scalars
+/// — RSScript's `Hashable` bound also admits `derives(Eq, Hash)` structs/sums and
+/// the structural `List`/`Option` containers over hashable types, all of which
+/// the compiled backend keys on directly. Equality reuses `VmValue`'s structural
+/// `PartialEq`; `Hash` is a matching recursive projection (see [`hash_vm_value`]),
+/// so equal keys hash equal and the VM stays in lockstep with the derived
+/// `Hash`/`Eq` of the lowered Rust.
+#[derive(Debug, Clone)]
+pub(crate) struct VmMapKey(VmValue);
 
 impl VmMapKey {
-    pub(crate) fn display(&self) -> String {
-        match self {
-            Self::Bool(value) => value.to_string(),
-            Self::Int(value) => value.to_string(),
-            Self::String(value) => value.to_string(),
+    pub(crate) fn new(value: VmValue) -> Self {
+        VmMapKey(value)
+    }
+
+    pub(crate) fn from_string(value: impl Into<String>) -> Self {
+        VmMapKey(VmValue::string(value))
+    }
+
+    /// The underlying value, returned as-is by `Map.keys()` / `Set.to_list()`.
+    pub(crate) fn value(&self) -> &VmValue {
+        &self.0
+    }
+
+    /// The key's string contents, when it is a `String` key (e.g. JSON object
+    /// keys must be strings).
+    pub(crate) fn as_str(&self) -> Option<&str> {
+        match &self.0 {
+            VmValue::String(value) => Some(value),
+            _ => None,
         }
     }
 
+    pub(crate) fn display(&self) -> String {
+        self.0.display()
+    }
+
     pub(crate) fn native_value(&self) -> NativeValue {
-        match self {
-            Self::Bool(value) => NativeValue::Bool(*value),
-            Self::Int(value) => NativeValue::Int(*value),
-            Self::String(value) => NativeValue::String(value.to_string()),
+        // Every hashable key has a native form; the string fallback only covers
+        // shapes the host ABI lacks a slot for (e.g. an `Option` key), keeping
+        // this total rather than panicking on the boundary.
+        self.0
+            .native_value()
+            .unwrap_or_else(|| NativeValue::String(self.0.display()))
+    }
+}
+
+impl PartialEq for VmMapKey {
+    fn eq(&self, other: &Self) -> bool {
+        self.0 == other.0
+    }
+}
+
+impl Eq for VmMapKey {}
+
+impl std::hash::Hash for VmMapKey {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        hash_vm_value(&self.0, state);
+    }
+}
+
+/// Recursively hash a `VmValue` consistently with [`VmValue`]'s `PartialEq`:
+/// equal values must hash equal. `Managed` is transparent in equality, so it is
+/// unwrapped here *before* the discriminant is mixed in (a `Managed(Int(1))`
+/// must hash like `Int(1)`). `Float` keys cannot occur (not `Hashable`), but the
+/// ±0.0 case is normalized anyway so the function is a correct `Hash` for any
+/// `VmValue`.
+fn hash_vm_value<H: std::hash::Hasher>(value: &VmValue, state: &mut H) {
+    use std::hash::Hash;
+
+    if let VmValue::Managed(inner) = value {
+        hash_vm_value(&inner.borrow(), state);
+        return;
+    }
+
+    std::mem::discriminant(value).hash(state);
+    match value {
+        VmValue::Unit | VmValue::OptionNone => {}
+        VmValue::Bool(value) => value.hash(state),
+        VmValue::Int(value) => value.hash(state),
+        VmValue::Char(value) => value.hash(state),
+        VmValue::String(value) => value.hash(state),
+        VmValue::Bytes(value) => value.hash(state),
+        VmValue::Float(value) => {
+            let bits = if *value == 0.0 { 0 } else { value.to_bits() };
+            bits.hash(state);
+        }
+        VmValue::Json(value) => value.to_string().hash(state),
+        VmValue::List(items) => {
+            let items = items.borrow();
+            items.len().hash(state);
+            for item in items.iter() {
+                hash_vm_value(item, state);
+            }
+        }
+        VmValue::Deque(items) => {
+            let items = items.borrow();
+            items.len().hash(state);
+            for item in items.iter() {
+                hash_vm_value(item, state);
+            }
+        }
+        VmValue::OptionSome(inner) => hash_vm_value(inner, state),
+        VmValue::Struct(data) | VmValue::Variant(data) => {
+            data.name.hash(state);
+            for field in &data.fields {
+                hash_vm_value(field, state);
+            }
+        }
+        VmValue::Native(data) => {
+            data.type_name.hash(state);
+            data.id.hash(state);
+        }
+        // Not a hashable key shape (the checker rejects `Map`/closure keys), but
+        // stay total: an order-independent fold so equal maps hash equally.
+        VmValue::Map(entries) => {
+            let mut acc: u64 = 0;
+            for (key, value) in entries.borrow().iter() {
+                let mut hasher = FnvHasher::default();
+                key.hash(&mut hasher);
+                hash_vm_value(value, &mut hasher);
+                acc = acc.wrapping_add(std::hash::Hasher::finish(&hasher));
+            }
+            acc.hash(state);
         }
+        VmValue::Closure(closure) => (Rc::as_ptr(closure) as usize).hash(state),
+        VmValue::Managed(_) => unreachable!("Managed handled above"),
     }
 }
 

crates/rsscript/tests/backend_differential.rs

@@ -419,6 +419,53 @@ fn main() -> Unit {
     common::differential::assert_backends_agree("struct-field-writes.rss", source, &[]);
 }
 
+/// A `derives(Eq, Hash)` struct (with nested `List`/`Option` fields) used as a
+/// `Map` key and `Set` element. The VM keys on a structural projection of the
+/// value while the compiled backend keys on the derived `Hash`/`Eq`; both must
+/// agree on dedup (a structurally-equal, separately-constructed key overwrites),
+/// membership, and the round-trip through `Map.keys()` (key value reconstruction).
+/// Output is reduced to counts/booleans so hash *iteration order* — which legitimately
+/// differs between the backends — is not under test. interp == jit == compiled.
+#[test]
+fn backends_agree_on_struct_keyed_collections() {
+    let source = "\
+struct Point derives(Clone, Eq, Hash) {
+    x: Int,
+    y: Int,
+    tags: List<Int>
+}
+
+fn main() -> Unit {
+    let counts = Map.new<Point, Int>()
+    let p1 = Point(x: 1, y: 2, tags: List.new<Int>())
+    let p2 = Point(x: 3, y: 4, tags: List.new<Int>())
+    // Structurally identical to `p1` but a distinct allocation.
+    let p1_again = Point(x: 1, y: 2, tags: List.new<Int>())
+
+    Map.insert(map: mut counts, key: read p1, value: read 10)
+    Map.insert(map: mut counts, key: read p2, value: read 20)
+    // Same structural key: overwrites rather than adds.
+    Map.insert(map: mut counts, key: read p1_again, value: read 99)
+
+    Log.write(message: read String.from_int(value: Map.len(map: read counts)))
+    Log.write(message: read String.from_bool(value: Map.contains_key(map: read counts, key: read p1_again)))
+    let absent = Point(x: 9, y: 9, tags: List.new<Int>())
+    Log.write(message: read String.from_bool(value: Map.contains_key(map: read counts, key: read absent)))
+    // Round-trips keys back to `Point` values (key reconstruction).
+    Log.write(message: read String.from_int(value: List.len(list: read Map.keys(map: read counts))))
+
+    let seen = Set.new<Point>()
+    Set.insert(set: mut seen, value: read p1)
+    Set.insert(set: mut seen, value: read p2)
+    Set.insert(set: mut seen, value: read p1_again)
+    Log.write(message: read String.from_int(value: Set.len(set: read seen)))
+    Log.write(message: read String.from_bool(value: Set.contains(set: read seen, value: read p1_again)))
+    return Unit
+}
+";
+    common::differential::assert_backends_agree("struct-keyed-collections.rss", source, &[]);
+}
+
 /// Deque / Set / SortedSet / SortedMap mutations with out-of-order inserts,
 /// duplicates, and removes, then sorted/ordered dumps. This gates the collection
 /// backing/representation optimizations: the VM (`Vec`-backed) and the compiled