Merge feat/capability: capability objects (keyword sugar + VM dynamic dispatch)

Third spec-todo roadmap feature (git worktree, merged once fully working: full
parity sweep + clippy green). Includes a VM CallDynamic fix that also repairs
generic protocol-bound dispatch parity.

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

Author: olwang

crates/rsscript/src/hir.rs

@@ -208,7 +208,9 @@ pub struct HirEffectEvent {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum HirReturnProof {
     NoValue,
-    Ident { name: String },
+    Ident {
+        name: String,
+    },
     StructConstructor,
     FreshCall,
     /// A literal (string, number, or boolean). A literal owns no borrowed or
@@ -718,6 +720,30 @@ impl Hir {
         }
     }
 
+    /// Concrete impl targets for a protocol method: `(implementing type name,
+    /// target function name)` for every `impl Protocol for Type` that maps
+    /// `method`. Used by the reg-VM to dynamically dispatch a `Protocol.method`
+    /// call by the receiver's runtime type (capability objects + generic bounds),
+    /// mirroring the compiled backend's closed-world enum dispatch.
+    pub(crate) fn protocol_method_targets(
+        &self,
+        protocol: &str,
+        method: &str,
+    ) -> Vec<(String, String)> {
+        let protocol = type_root_name(protocol);
+        let method = type_root_name(method);
+        self.protocol_impls
+            .iter()
+            .filter(|imp| imp.protocol == protocol)
+            .filter_map(|imp| {
+                imp.mappings
+                    .iter()
+                    .find(|mapping| mapping.method == method)
+                    .map(|mapping| (imp.type_name.clone(), mapping.target.clone()))
+            })
+            .collect()
+    }
+
     pub fn resolve_function(&self, namespace: Option<&str>, name: &str) -> Option<&FunctionSig> {
         if let Some(namespace) = namespace
             && let Some(signature) = self.signatures.get(&qualified_key(namespace, name))
@@ -3228,7 +3254,11 @@ fn collect_struct_pattern_binding_types(
         };
         let field_type_name = substitute_type_params(&field_type.type_name, substitutions);
         if let Some(pattern) = &field.pattern {
-            bindings.extend(match_pattern_binding_types(hir, pattern, Some(&field_type_name)));
+            bindings.extend(match_pattern_binding_types(
+                hir,
+                pattern,
+                Some(&field_type_name),
+            ));
         } else if let Some(binding) = &field.binding {
             bindings.push((binding.clone(), field_type_name));
         }

crates/rsscript/src/reg_vm/mod.rs

@@ -1708,6 +1708,17 @@ enum RegInstr {
         /// `&mut` semantics.
         mut_args: Vec<usize>,
     },
+    /// Dynamic protocol dispatch: a `Protocol.method(self: x, ...)` call whose
+    /// concrete impl is chosen at runtime by `args[0]`'s struct type name. This is
+    /// how capability objects and generic protocol bounds dispatch in the VM,
+    /// mirroring the compiled backend's closed-world enum dispatch. `dispatch`
+    /// maps each implementing struct name to the impl's target function id.
+    CallDynamic {
+        dst: Reg,
+        dispatch: Vec<(String, usize)>,
+        args: Vec<Reg>,
+        mut_args: Vec<usize>,
+    },
     /// `spawn f(args)` / `async let`: start `function` as a new concurrent task
     /// and put a Task handle in `dst` (the spawning task keeps running).
     SpawnTask {
@@ -5125,6 +5136,36 @@ impl RegLowerer<'_> {
                             });
                             return Ok(dst);
                         }
+                        // Dynamic protocol dispatch: `Protocol.method(self: x, ...)`
+                        // where `Protocol` is a protocol with impls. The concrete
+                        // function is selected at runtime by `args[0]`'s struct type
+                        // (capability objects + generic bounds) — the VM equivalent
+                        // of the compiled backend's closed-world enum dispatch.
+                        // Checked before the `function_ids` lookup because a protocol
+                        // method also appears there as a bodyless stub (which would
+                        // wrongly return `Unit`).
+                        let dispatch: Vec<(String, usize)> = self
+                            .hir
+                            .protocol_method_targets(namespace_root, name_root)
+                            .into_iter()
+                            .filter_map(|(type_name, target)| {
+                                self.function_ids
+                                    .get(type_root_name(&target))
+                                    .copied()
+                                    .map(|function| (type_name, function))
+                            })
+                            .collect();
+                        if !dispatch.is_empty() {
+                            let mut_args =
+                                self.native_mut_arg_positions(Some(namespace_root), name_root);
+                            self.emit(RegInstr::CallDynamic {
+                                dst,
+                                dispatch,
+                                args: arg_regs,
+                                mut_args,
+                            });
+                            return Ok(dst);
+                        }
                         if let Some(function) = self.function_ids.get(&qualified_key).copied() {
                             let mut_args =
                                 self.native_mut_arg_positions(Some(namespace_root), name_root);
@@ -5363,9 +5404,7 @@ impl RegLowerer<'_> {
                                 .is_none_or(|pattern| self.is_supported_match_pattern(pattern))
                     })
             }
-            MatchPattern::List {
-                prefix, suffix, ..
-            } => prefix
+            MatchPattern::List { prefix, suffix, .. } => prefix
                 .iter()
                 .chain(suffix)
                 .all(|pattern| self.is_supported_match_pattern(pattern)),
@@ -5422,7 +5461,10 @@ impl RegLowerer<'_> {
         let mut failures = Vec::new();
         let required = (prefix.len() + suffix.len()) as i64;
         let len = self.temp();
-        self.emit(RegInstr::ListLen { dst: len, list: src });
+        self.emit(RegInstr::ListLen {
+            dst: len,
+            list: src,
+        });
         let bound = self.temp();
         self.emit(RegInstr::LoadInt {
             dst: bound,
@@ -7814,6 +7856,51 @@ impl RegVm {
                             });
                             continue 'frames;
                         }
+                        RegInstr::CallDynamic {
+                            dst,
+                            dispatch,
+                            args,
+                            mut_args,
+                        } => {
+                            // Select the concrete impl by the runtime struct type of
+                            // the receiver (args[0]), then call it like `CallKnown`.
+                            let receiver = self.reg(base + args[0]).clone();
+                            let type_name = match &receiver {
+                                VmValue::Struct(data) => Some(data.name.clone()),
+                                _ => None,
+                            };
+                            let callee_id = type_name.as_ref().and_then(|name| {
+                                dispatch
+                                    .iter()
+                                    .find(|(struct_name, _)| struct_name.as_str() == &**name)
+                                    .map(|(_, id)| *id)
+                            });
+                            let Some(callee_id) = callee_id else {
+                                return Err(EvalError::Runtime(format!(
+                                    "reg VM dynamic protocol dispatch found no impl for receiver `{}`.",
+                                    type_name.as_deref().unwrap_or("<non-struct value>")
+                                )));
+                            };
+                            let callee = Rc::clone(&unit.functions[callee_id]);
+                            self.prepare_frame(next_base, callee.regs);
+                            for (index, reg) in args.iter().enumerate() {
+                                let value = self.reg(base + *reg).clone();
+                                self.set_reg(next_base + index, value);
+                            }
+                            let mut_writeback = mut_args
+                                .iter()
+                                .map(|&pos| (base + args[pos], next_base + pos))
+                                .collect();
+                            self.frames.last_mut().expect("active frame").ip = ip;
+                            self.frames.push(Frame {
+                                func: callee,
+                                ip: 0,
+                                base: next_base,
+                                ret_dst: base + *dst,
+                                mut_writeback,
+                            });
+                            continue 'frames;
+                        }
                         RegInstr::SpawnTask {
                             dst,
                             function: callee_id,

crates/rsscript/src/syntax/parser.rs

@@ -3988,6 +3988,28 @@ fn parse_type_ref(tokens: &[Token], start: usize, end: usize) -> Option<TypeRef>
     if let Some(tuple) = parse_tuple_type_ref(tokens, start, end) {
         return Some(tuple);
     }
+    // `capability <Protocol>` (spec §20.2-2) is sugar for `Capability<<Protocol>>`:
+    // an explicit, review-visible dynamic-dispatch boundary. It may follow an
+    // effect keyword (`read capability Store<T>`); the effect is handled by the
+    // parameter parser, so skip it here when locating the `capability` marker.
+    if let Some(cap_index) = (start..end).find(|index| {
+        ident_name(&tokens[*index])
+            .is_some_and(|name| name != "read" && name != "mut" && name != "take")
+    }) && ident_name(&tokens[cap_index]).is_some_and(|name| name == "capability")
+    {
+        let inner = parse_type_ref(tokens, cap_index + 1, end)?;
+        return Some(TypeRef {
+            name: "Capability".to_string(),
+            args: vec![inner],
+            malformed_arg_spans: Vec::new(),
+            is_fresh: false,
+            is_noescape: false,
+            is_owned: false,
+            fn_params: Vec::new(),
+            fn_return: None,
+            span: tokens[cap_index].span.clone(),
+        });
+    }
     let is_fresh = tokens
         .get(start)
         .and_then(ident_name)

crates/rsscript/tests/checker_package/misc.rs

@@ -70,27 +70,28 @@ fn package_manager_spec_uses_current_http_and_env_facade_shapes() {
 }
 
 #[test]
-fn rss_spec_keeps_protocol_dynamic_dispatch_unimplemented() {
-    // Dynamic dispatch is now a committed in-scope roadmap item (§20.2), but it is
-    // still NOT implemented: the spec must not describe it as implemented, settled,
-    // or available to package contracts until it is actually built.
+fn rss_spec_documents_capability_dispatch_and_rejects_implicit_dyn() {
+    // Dynamic dispatch is implemented ONLY as the explicit `Capability<Protocol>`
+    // form (§20.2-2). The spec must document that, and must still reject implicit
+    // protocol-typed values / Rust-style `dyn` coercion as non-goals.
     let spec = fs::read_to_string(common::language_spec_path())
         .unwrap_or_else(|error| panic!("RSScript spec should read: {error}"));
 
     for forbidden in [
-        "Dynamic dispatch (admitted",
         "RSScript admits protocol-typed dynamic dispatch",
-        "The design decision is settled: dynamic dispatch is supported",
+        "implicit dyn coercion is supported",
         "form is admitted, not excluded",
         "protocol_dynamic_dispatch",
     ] {
         assert!(
             !spec.contains(forbidden),
-            "protocol dynamic dispatch must remain deferred, found `{forbidden}`"
+            "implicit dynamic dispatch must stay a non-goal, found `{forbidden}`"
         );
     }
-    assert!(spec.contains("Dynamic dispatch (in scope §20.2; not yet implemented)"));
-    assert!(spec.contains("does not yet implement protocol-typed dynamic dispatch"));
-    assert!(spec.contains("The only implemented and specified protocol call form is"));
-    assert!(spec.contains("explicit `Protocol.method(...)` dispatch"));
+    assert!(spec.contains("Dynamic dispatch (explicit capability form implemented §20.2-2)"));
+    assert!(
+        spec.contains("`Capability<Protocol>` form (with the `capability Protocol` keyword sugar)")
+    );
+    assert!(spec.contains("Rust-style `dyn Trait` vtable coercion"));
+    assert!(spec.contains("`Protocol.method(...)` dispatch backed by an explicit generic bound"));
 }

crates/rsscript/tests/vm_eval_parity/misc.rs

@@ -1410,3 +1410,53 @@ fn main() -> Unit {
         source,
     );
 }
+
+#[test]
+fn parity_capability_dynamic_dispatch() {
+    // Capability objects (spec §20.2-2): `Capability<Protocol>` and the
+    // `capability Protocol` keyword form dispatch a protocol method by the
+    // value's runtime type. The reg-VM must select the same concrete impl as the
+    // compiled backend's closed-world enum dispatch (regression for the VM
+    // CallDynamic path; previously the VM returned Unit).
+    let source = r#"
+features: local
+
+protocol Greeter {
+    fn greet(self: read Self) -> fresh String
+}
+
+struct English { x: Int }
+struct French { x: Int }
+
+fn English.greet(self: read English) -> fresh String {
+    if self.x > 0 { return "hello" }
+    return "hi"
+}
+fn French.greet(self: read French) -> fresh String {
+    if self.x > 0 { return "bonjour" }
+    return "salut"
+}
+
+impl Greeter for English { greet = English.greet }
+impl Greeter for French { greet = French.greet }
+
+fn say(who: read capability Greeter) -> fresh String {
+    return Greeter.greet(self: read who)
+}
+
+fn main() -> Unit {
+    local e = English(x: 1)
+    local f = French(x: 2)
+    local a: Capability<Greeter> = Capability<Greeter>.from(value: take e)
+    local b: Capability<Greeter> = Capability<Greeter>.from(value: take f)
+    Log.write(message: read say(who: read a))
+    Log.write(message: read say(who: read b))
+    return Unit
+}
+"#;
+    common::assert_vm_eval_matches_backend(
+        "parity-capability-dispatch.rss",
+        "rsscript_parity_capability_dispatch",
+        source,
+    );
+}

docs/RSScript_v0.7_Spec.md

@@ -3642,19 +3642,20 @@ short-circuit `&&`/`||`, which is only conditionally evaluated. Hoisting it woul
 force unconditional evaluation, so such an `await` stays rejected as a non-linear
 await (`RS0411`).
 
-#### Dynamic dispatch (in scope §20.2; not yet implemented)
+#### Dynamic dispatch (explicit capability form implemented §20.2-2)
 
-RSScript v0.7 does not yet implement protocol-typed dynamic dispatch, trait
-objects, or protocol-typed values.
-The only implemented and specified protocol call form is
-static, explicit `Protocol.method(...)` dispatch backed by an explicit generic
-bound or an explicit `impl Protocol for Type` declaration.
+Dynamic dispatch in RSScript is **only** the explicit, review-visible
+`Capability<Protocol>` form (with the `capability Protocol` keyword sugar),
+implemented per §20.2-2: it lowers to a closed-world enum-of-impls with `match`
+dispatch on the compiled backend and dispatches by the receiver's runtime type in
+the reg-VM. RSScript does **not** implement implicit protocol-typed values (a bare
+`x: Protocol` parameter) or Rust-style `dyn Trait` vtable coercion — those stay
+non-goals (§21).
 
-Explicit, review-visible `capability`-bounded dispatch is now a **committed
-roadmap item** (§20.2-2, §20.1-G) — not Rust-style implicit `dyn` coercion, which
-stays a non-goal (§21). Until it is built, it must not be described as
-implemented, settled, or available to package contracts: syntax, checking,
-lowering, review evidence, and package metadata must land together.
+Aside from capability objects, the only protocol call form is static, explicit
+`Protocol.method(...)` dispatch backed by an explicit generic bound or an explicit
+`impl Protocol for Type` declaration. Implicit `dyn` coercion must not be described
+as implemented, settled, or available to package contracts.
 
 Closed sets should still prefer sealed sum types with exhaustive match
 (section 20.1), which are strictly more reviewable. For open sets such as
@@ -5321,10 +5322,13 @@ F. Registry-level review-risk badges
      signals to derive from compiler/package review evidence.
 
 G. Capability objects (explicit dynamic dispatch)
-   - now in scope: committed roadmap (§20.2).
+   - implemented (§20.2-2): `Capability<Protocol>` (and the `capability Protocol`
+     keyword sugar) is an explicit, review-visible dynamic-dispatch boundary. The
+     compiled backend lowers it to a closed-world enum-of-impls with `match`
+     dispatch (no `dyn`); the reg-VM dispatches the same impl by the receiver's
+     runtime type. Construct with `Capability<Protocol>.from(value: take x)`.
    - RSScript does not adopt Rust-style `dyn Trait` with vtable coercion.
-   - if dynamic dispatch is needed, it must use an explicit capability-bounded
-     form that is visible to review:
+   - the explicit capability-bounded form is visible to review:
 
        fn serve(store: read capability Store<Image>) -> Result<Unit, Error>
 

docs/spec-todo.md

@@ -32,13 +32,18 @@ model without reversing a review-first tenet. Ordered by readiness/value.
   view-of-a-view) and the `scoped-view-escape.rss` fail fixture (`RS0702`). The
   `with Buffer.view(...) as v { … }` form also already works.
 
-- [ ] **Capability objects / explicit dynamic dispatch** (§3.2, §20.1-G, §20.2-2) —
-  _large._ Review-visible `capability`-bounded dispatch
-  (`store: read capability Store<T>`), **not** Rust-style implicit `dyn` coercion
-  (which stays a non-goal, §21). The review map must flag every capability boundary;
-  capability values carry their protocol's effect declarations (no silent widening).
-  _Touches:_ parser/types, protocol resolution, lowering (vtable-free representation),
-  review map / REIR. Must hold parity.
+- [x] **Capability objects / explicit dynamic dispatch** (§3.2, §20.1-G, §20.2-2) —
+  _done._ The compiled backend already lowered `Capability<Protocol>` to a
+  closed-world enum-of-impls with `match` dispatch (no `dyn`); this completes the
+  feature: (1) the spec's `capability Protocol` keyword form now parses as sugar for
+  `Capability<Protocol>` (parser desugar), so `who: read capability Greeter` and
+  `local x: capability Greeter` work; (2) **fixed a real VM parity bug** — the reg-VM
+  had *no* runtime dynamic dispatch, so any `Protocol.method(self: x, …)` call
+  (capability objects *and* generic bounds) returned `Unit` instead of dispatching.
+  Added a `CallDynamic` instruction + `Hir::protocol_method_targets` that selects the
+  concrete impl by the receiver's runtime struct type, mirroring the compiled enum
+  dispatch. Verified at parity (`parity_capability_dynamic_dispatch`, two impls). The
+  review map already flags dynamic dispatch (`has_dynamic_protocol_dispatch`).
 
 - [ ] **Cross-isolate message API (zero-copy transfer)** (§20.1-B, §20.2-3) —
   _large._ Typed send/receive channels between isolates; payloads are Copy/owned data