rss: nested generics, sound payload-variant construction, borrowed-match extraction, callable clone

- RSS-12: nested generic type-args in method calls (parser angle-depth fix)
- RSS-13: user sum payload-variant construction — resolve (hir) + lower (rust_lower qualified
  Enum::Variant{..}), now fully typed & checked: sum-type inference, named-field-only (RS0201),
  arity/unknown/duplicate/missing coverage (RS0203/4/5), per-field value-type check (RS0207),
  field-type-aware lowering (Int32 -> 1i32)
- RSS-14: borrowed-match payload extraction — force-borrow field-place scrutinees, deref-shadow
  Copy payloads (let v = *v) so read-param matches bind without move/mismatch
- RSS-15: callable explicit .clone() for derives(Clone) user types; gate mirrors compute_derive_attr
  (empty-derive non-resource cloneable, explicit-without-Clone/resource not); excluded from the
  read-receiver re-borrow arg rule
- docs: BUGS.md RSS-12..15 (+ follow-up rounds); v0.6 spec variant-construction note; fixture comment

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

Author: Haofei

BUGS.md

@@ -216,3 +216,85 @@ fn main() -> Unit {
   never nests generics more than a handful of levels, and the item is rated LOW / non-correctness.
   The risk of regressing generics resolution was judged disproportionate to the benefit, so the fix
   is left for a dedicated change rather than bundled with the RSS-1…RSS-10 correctness fixes.
+
+---
+
+## Added during tinygrad-port work (2026-06-11)
+
+### RSS-12 — [FIXED] — Nested generic type-arguments in method calls parsed as comparisons
+- **Source:** `crates/rsscript/src/syntax/parser.rs` `find_top_level_operator` (~:3031).
+- `List.new<List<Int>>()`, `List.get<List<Int>>(...)`, `List.len<List<Int>>(...)` all failed with
+  RS0015 "unsupported syntax". The binary-operator splitter tracked `angle_depth` asymmetrically:
+  it decremented on a nested inner `>` but never incremented on the nested inner `<` (the inner
+  `<` of `List<Int>` is not a generic-open per `is_generic_angle_open`, which requires the matching
+  `>` to be followed by `.`/`(`), so `angle_depth` hit 0 one `>` early and the outer `>` was parsed
+  as a `Greater` comparison → the call collapsed to `Expr::Unknown`.
+- **Fix:** inside a generic argument list (`angle_depth > 0`), also `angle_depth += 1` on `<`. Inside
+  a type-argument list `<` is unambiguously a nested generic open, never a comparison.
+- **Verified:** `List<List<Int>>` build/index/len/param all parse, typecheck, and run.
+
+### RSS-13 — [FIXED] — User sum payload-variant construction did not resolve/lower
+- Previously documented in fixtures as "user payload-variant construction is not yet executable":
+  declaring and `match`ing payload variants worked, but constructing one (`ArgInt(value: 5)`,
+  `Shape.Circle(radius: 5)`) failed with RS0206 "does not resolve" / a backend "cannot find tuple
+  variant" error.
+- **Sources / fix (two sites):**
+  1. `crates/rsscript/src/hir.rs` `resolve_call` (~:762): also resolve a call as
+     `CallResolution::EnumVariant` when `self.sum_type_for_variant(name).is_some()` (not only the
+     builtins Ok/Err/Some/None). The reg-VM already lowered `MakeVariant` via `sum_variant_fields`.
+  2. `crates/rsscript/src/rust_lower/lowerer.rs` constructor lowering (~:2412): emit the qualified,
+     struct-style form `Enum::Variant { field: value, ... }` (nullary: `Enum::Variant`) for user sum
+     variants, matching the lowered enum (whose payload variants use named fields), instead of the
+     bare/tuple fall-through.
+- **Verified:** construct + `match`/discriminate + extract (via owned/`take` scrutinee) all run.
+- **Known follow-up:** extracting a *Copy* payload (Int/Float) directly from a *borrowed* (`read`)
+  match still needs the binding deref'd (use an owned `take`/cloned scrutinee for now).
+
+### RSS-15 — [ADDED] — Explicit, callable `.clone()` for `derives(Clone)` types
+- Previously only implicit clone existed (e.g. `read` args retained into a collection); there was no
+  surface syntax to deep-copy a user value, and `derives(Copy)` on a sum is rejected. This blocked
+  rebuilding immutable graph nodes (e.g. a UOp simplifier).
+- **Added (kept implicit clone):**
+  - `hir.rs` `resolve_receiver_call`: when no method candidate resolves and the method is `clone`,
+    synthesize a builtin sig `(self: read T) -> fresh T` so `x.clone()` resolves and types as `T`.
+  - `rust_lower/lowerer.rs` receiver-call lowering: for a user struct/sum receiver, emit
+    `{receiver}.clone()` (Rust's derived Clone = deep copy). Gated to user types so builtins
+    (JSON/Map/List) keep their own clone lowering (`json_clone`, …).
+  - `rust_lower/lowerer.rs` `lower_call_arg_for_expected_type`: exclude `clone` from the
+    "`read` receiver-call result is re-borrowed" rule — `.clone()` yields an owned value, so passing
+    it to a by-value param must not add `&` (was emitting `&x.clone()` into an owned param).
+- **Verified:** clone of struct/sum/field; clone passed to a by-value param; whole rss suite green.
+
+### RSS-13 follow-ups — [FIXED] — payload-variant construction is now typed & checked
+- (Audit found the initial RSS-13 resolved variant calls but did not type/check them.)
+- **P1 type:** `hir.rs` `infer_enum_variant_type` now returns the variant's sum type for user variants
+  (was only Some/Ok/Err), so `Number(value: 5)` has type `Token` and misuse (e.g. passing it to a
+  `read String` param) is caught (RS0207) instead of emitting invalid Rust.
+- **P1 check / no panic:** `checks/calls.rs` `check_enum_variant_form` validates user-variant
+  construction against declared fields — unknown field name (RS0203), wrong arity (RS0203/RS0204) —
+  so a malformed constructor (`Number(1, 2)`, `Number(bad: 5)`) is a checker error, not an
+  out-of-bounds panic in the lowerer.
+- **P2 field types:** `rust_lower/lowerer.rs` variant construction lowers each arg against its declared
+  field type (mirroring struct ctors) and resolves fields by name bounds-safely. Note: once round-2
+  value-type checking landed, `Tiny(value: 1)` with `value: Int32` is *rejected* at check (RS0207, an
+  `Int` literal is not `Int32`) — same as struct constructors; the field-type lowering applies to
+  values that already have the field's type (e.g. an `Int32`-typed binding), which lower without a cast.
+
+### RSS-13 follow-ups (round 2) — [FIXED] — duplicate fields & field-value types
+- (Second audit: the round-1 variant checker tracked names/counts but not duplicates or value types.)
+- **Exactly-once coverage:** `check_enum_variant_form` now tracks per-field coverage — duplicate field
+  (RS0205), unknown field (RS0203), too many (RS0203), and any unfilled field (RS0204). So
+  `Both(left: 1, left: 2)` reports duplicate `left` + missing `right` (was: passed check, then E0062).
+- **Value types:** each variant field value is type-checked against its declared field type (reusing
+  `argument_type_matches` + the JSON/Map/List literal acceptances, like binding-payload checks). So
+  `Number(value: "x")` for `value: Int` reports RS0207 (was: passed check, then E0308).
+
+### RSS-15 / RSS-13 follow-ups (round 3) — [FIXED] — clone gated on `Clone`; variants are named-only
+- **`.clone()` only for `Clone`-deriving types:** the synthesized clone previously resolved for *any*
+  user type, so `struct Boxy derives(Eq)` passed `check` then failed Rust with E0599. Now `Hir` tracks
+  `clone_types` (declared types whose derive list includes `Clone`); `resolve_receiver_call` synthesizes
+  `clone` only for those (non-user receivers keep prior behavior), and rust_lower emits `.clone()` only
+  when `type_derives_clone(root)`. A declared type without `Clone` now reports RS0206 at check time.
+- **Variants are named-field-only:** `check_enum_variant_form` rejects any unnamed payload arg
+  (RS0201), matching the v0.6 spec (variants use the same named-field construction form as structs).
+  `Number(5)` is now a checker error instead of lowering to `Token::Number { value: 5i64 }`.

crates/rsscript/src/checks/calls.rs

@@ -1721,6 +1721,109 @@ fn check_enum_variant_form(
     call_span: &Span,
 ) {
     let variant = callee_name(callee);
+    // User sum variants: validate construction against the variant's declared fields. Each field
+    // must be supplied exactly once (no unknown name, no duplicate, none missing) and each value is
+    // type-checked against its declared field type — so a malformed/ill-typed constructor is a
+    // checker error rather than a lowerer panic or a mapped rustc error.
+    if let Some(fields) = analyzer.hir.sum_variant_fields(&variant).map(|fields| {
+        fields
+            .iter()
+            .map(|f| (f.name.clone(), f.type_name.clone()))
+            .collect::<Vec<(String, String)>>()
+    }) {
+        // Variants use the same named-field construction form as structs (per the v0.6 spec);
+        // positional/unnamed payload args are not allowed.
+        if let Some(unnamed) = args.iter().find(|arg| arg.name.is_none()) {
+            analyzer.diagnostics.push(Diagnostic::error(
+                code::UNNAMED_ARGUMENT,
+                format!(
+                    "variant `{variant}` must be constructed with named fields, e.g. `{variant}(field: value)`."
+                ),
+                unnamed.span.clone(),
+                "variant field must be named",
+            ));
+            return;
+        }
+        let mut seen = vec![false; fields.len()];
+        for (index, arg) in args.iter().enumerate() {
+            // Resolve which field this arg targets: by name if given, else positionally.
+            let field_idx = match &arg.name {
+                Some(name) => match fields.iter().position(|(fname, _)| fname == name) {
+                    Some(i) => i,
+                    None => {
+                        analyzer.diagnostics.push(Diagnostic::error(
+                            code::UNKNOWN_ARGUMENT,
+                            format!("variant `{variant}` has no field `{name}`."),
+                            arg.span.clone(),
+                            "unknown variant field",
+                        ));
+                        continue;
+                    }
+                },
+                None if index < fields.len() => index,
+                None => {
+                    analyzer.diagnostics.push(Diagnostic::error(
+                        code::UNKNOWN_ARGUMENT,
+                        format!(
+                            "variant `{variant}` has {} field(s) but {} were given.",
+                            fields.len(),
+                            args.len()
+                        ),
+                        arg.span.clone(),
+                        "too many variant fields",
+                    ));
+                    continue;
+                }
+            };
+            if seen[field_idx] {
+                analyzer.diagnostics.push(Diagnostic::error(
+                    code::DUPLICATE_ARGUMENT,
+                    format!(
+                        "variant `{variant}` field `{}` is provided more than once.",
+                        fields[field_idx].0
+                    ),
+                    arg.span.clone(),
+                    "duplicate variant field",
+                ));
+                continue;
+            }
+            seen[field_idx] = true;
+            // Type-check the value against the declared field type (mirrors binding-payload checks:
+            // accept matching JSON/Map/List literals, skip unresolved generics, else require a match).
+            let expected = fields[field_idx].1.as_str();
+            if json_value_accepts_literal(expected, &arg.value)
+                || check_map_literal_type(analyzer, expected, &arg.value, "variant field")
+                || check_list_literal_type(analyzer, expected, &arg.value, "variant field")
+            {
+                continue;
+            }
+            if let Some(actual) = hir_expr_type_name(&arg.value)
+                && !unresolved_generic_type(actual)
+                && !argument_type_matches(expected, actual)
+            {
+                analyzer.diagnostics.push(Diagnostic::error(
+                    code::ARGUMENT_TYPE_MISMATCH,
+                    format!(
+                        "variant `{variant}` field `{}` has type `{actual}`, expected `{expected}`.",
+                        fields[field_idx].0
+                    ),
+                    hir_expr_span(&arg.value).clone(),
+                    "variant field type mismatch",
+                ));
+            }
+        }
+        for (i, provided) in seen.iter().enumerate() {
+            if !provided {
+                analyzer.diagnostics.push(Diagnostic::error(
+                    code::MISSING_ARGUMENT,
+                    format!("variant `{variant}` is missing field `{}`.", fields[i].0),
+                    call_span.clone(),
+                    "missing variant field",
+                ));
+            }
+        }
+        return;
+    }
     let valid = match variant.as_str() {
         "Ok" | "Err" | "Some" => args.len() == 1 && args[0].name.is_none(),
         "None" | "Result" | "Option" => false,

crates/rsscript/src/hir.rs

@@ -460,6 +460,8 @@ pub struct HirFunctionBody {
 pub struct Hir {
     signatures: HashMap<String, FunctionSig>,
     types: HashMap<String, TypeInfo>,
+    // user-declared types whose derive list includes `Clone` (gates the synthesized `.clone()`)
+    clone_types: HashSet<String>,
     fields_by_name: HashMap<String, Vec<FieldInfo>>,
     sum_variant_types: HashMap<String, String>,
     sum_variant_fields: HashMap<String, Vec<FieldInfo>>,
@@ -614,6 +616,14 @@ impl Hir {
                         &type_decl.name,
                         &type_decl.span,
                     );
+                    // Mirror rust_lower's derive emission: an omitted derive list defaults to
+                    // Debug+Clone for non-resource types, so those are cloneable too.
+                    if type_decl.derives.iter().any(|d| d == "Clone")
+                        || (type_decl.derives.is_empty()
+                            && type_decl.kind != TypeKind::Resource)
+                    {
+                        self.clone_types.insert(type_decl.name.clone());
+                    }
                     self.insert_type(type_info_from_decl(type_decl));
                 }
                 Item::SumType(sum) => {
@@ -636,6 +646,10 @@ impl Hir {
                         fields_ordered: Vec::new(),
                         fields: HashMap::new(),
                     };
+                    // Sums are never resources; an omitted derive list defaults to Debug+Clone.
+                    if sum.derives.is_empty() || sum.derives.iter().any(|d| d == "Clone") {
+                        self.clone_types.insert(sum.name.clone());
+                    }
                     self.insert_type(type_info);
                     for variant in &sum.variants {
                         self.sum_variant_types
@@ -760,7 +774,11 @@ impl Hir {
 
     pub fn resolve_call(&self, callee: &Callee) -> CallResolution {
         let call_name = callee_name(callee);
-        if is_enum_variant_call(call_name) {
+        // Builtin variants (Ok/Err/Some/None) and user-declared sum variants are both
+        // constructor calls. The reg-VM lowerer already builds user payload variants via
+        // `sum_variant_fields`; recognizing them here lets construction resolve instead of
+        // being reported as an unknown callee.
+        if is_enum_variant_call(call_name) || self.sum_type_for_variant(call_name).is_some() {
             return CallResolution::EnumVariant;
         }
 
@@ -803,6 +821,43 @@ impl Hir {
     ) -> (CallResolution, Option<String>) {
         let candidates = self.receiver_call_candidates(receiver_type, method, value_types);
         if candidates.is_empty() {
+            // A declared (user) type only gets the synthesized `.clone()` if it derives `Clone`;
+            // otherwise leave the call unresolved (RS0206) instead of emitting an `.clone()` that
+            // Rust would reject (E0599). Non-user receivers keep their existing resolution.
+            let clone_allowed = {
+                let root = type_root_name(receiver_type);
+                !self.types.contains_key(root) || self.clone_types.contains(root)
+            };
+            if method == "clone" && clone_allowed {
+                // Every value supports an explicit `.clone()` returning a fresh copy of the
+                // receiver's type. The runtime already clones implicitly (e.g. `read` args stored
+                // into a collection); this exposes that as a callable for any `derives(Clone)` type.
+                return (
+                    CallResolution::Resolved {
+                        signature: FunctionSig {
+                            namespace: Some(type_root_name(receiver_type).to_string()),
+                            name: "clone".to_string(),
+                            is_public: true,
+                            is_async: false,
+                            is_native: false,
+                            type_params: Box::from([]),
+                            type_param_bounds: Vec::new(),
+                            params: vec![ParamSig {
+                                name: "self".to_string(),
+                                effect: Some(ParamEffect::Read),
+                                type_name: receiver_type.to_string(),
+                            }],
+                            return_type: Some(receiver_type.to_string()),
+                            returns_fresh: true,
+                            effects: Vec::new(),
+                            retained_params: HashSet::new(),
+                            is_builtin: true,
+                        },
+                        kind: ResolvedCalleeKind::BuiltinFunction,
+                    },
+                    Some(type_root_name(receiver_type).to_string()),
+                );
+            }
             return (CallResolution::Unknown, None);
         }
         if candidates.len() > 1 {
@@ -2422,8 +2477,9 @@ fn infer_enum_variant_type(
         "Some" => Some(format!("Option<{}>", payload_type(args)?)),
         "Ok" => Some(format!("Result<{}, E>", payload_type(args)?)),
         "Err" => Some(format!("Result<T, {}>", payload_type(args)?)),
-        // `None` and bare `Option`/`Result` carry no inferable payload type.
-        _ => None,
+        // A user-declared sum variant constructs a value of its sum type, so a `Number(value: 5)`
+        // call has type `Token` — letting the normal arg/binding type checks catch misuse.
+        _ => hir.sum_type_for_variant(variant).map(str::to_string),
     }
 }