feat(vectorization): broaden to n-ary operator forms and recover return-type precision 📐

Implements docs/design/vectorization.md (RFC steps 1-5 + 7; step 6
compiler unrolling deferred).

Parser marks operator-form calls with operator_form: bool. Scope
resolution synthesises vec variants for each scalar overload of a per-
position LUB-collapsed sig. Each Candidate now records vectorized: bool;
runtime dispatch iterates one candidate list (scalars first, vecs after)
and checks every element pair against the underlying scalar's parameter
types — fixing the existing first-pair-only bug where (1, "a") + (2, "b")
would crash on element 1.

Return-type inference: scalar bindings keep their declared return; vec
bindings yield Tuple<elem_return; max_len>; Dynamic LUBs across all
candidates' inferred returns, naturally recovering precise scalar LUB
for the common case PR #140 had to pessimise to Any.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Author: timfennis

manual/src/reference/types/tuple.md

@@ -43,3 +43,29 @@ assert_eq(b, (1,2,3,4,5));
 ## Operators
 
 {{#include ../../snippets/list-operators.md}}
+
+## Vectorization
+
+Operators broadcast element-wise over tuples. Both arguments must be tuples
+of the same length, or one side may be a scalar that broadcasts:
+
+```ndc
+assert_eq((1, 2) + (3, 4), (4, 6));
+assert_eq(-(1, 2, 3), (-1, -2, -3));
+assert_eq((1, 2) + 5, (6, 7));
+assert_eq(("a", "b") ++ ("c", "d"), ("ac", "bd"));
+```
+
+Vectorization only kicks in for operator syntax (`a + b`, `-x`,
+`a ++ b`, etc.). Regular function calls never broadcast, so
+`f((1, 2, 3))` passes the whole tuple to `f` and does not call `f`
+once per element.
+
+Mixed-element tuples or length mismatches error rather than silently
+producing wrong results:
+
+```ndc
+(1, 2, 3) + (4, 5)        // ERROR: no overload matches
+(1, "a") + (2, "b")       // ERROR: no overload accepts both pairs
+```
+

ndc_analyser/src/analyser.rs

@@ -6,8 +6,8 @@ use itertools::{Itertools, izip};
 use ndc_core::{StaticType, TypeSignature};
 use ndc_lexer::Span;
 use ndc_parser::{
-    Binding, Expression, ExpressionLocation, ForBody, ForIteration, FunctionParameter, Lvalue,
-    NodeId,
+    Binding, Candidate, Expression, ExpressionLocation, ForBody, ForIteration, FunctionParameter,
+    Lvalue, NodeId,
 };
 
 /// Side table holding semantic information keyed by AST node identity.
@@ -130,7 +130,7 @@ impl Analyser {
                     return Ok(StaticType::Any);
                 };
 
-                *resolved = Binding::Resolved(binding);
+                *resolved = Binding::Resolved(Candidate::scalar(binding));
 
                 Ok(self.scope_tree.get_type(binding).clone())
             }
@@ -202,12 +202,17 @@ impl Analyser {
                 let right_type = self.analyse_or_any(r_value);
                 let arg_types = vec![left_type, right_type];
 
-                *resolved_assign_operation = self
-                    .scope_tree
-                    .resolve_function_binding(&format!("{operation}="), &arg_types);
+                // OpAssignment desugars to `x = x op y` where `op` is operator-form,
+                // so vec dispatch must be available for both the in-place and the
+                // fallback regular operator overload.
+                *resolved_assign_operation = self.scope_tree.resolve_function_binding(
+                    &format!("{operation}="),
+                    &arg_types,
+                    true,
+                );
                 *resolved_operation = self
                     .scope_tree
-                    .resolve_function_binding(operation, &arg_types);
+                    .resolve_function_binding(operation, &arg_types, true);
 
                 if let Binding::None = resolved_operation {
                     self.emit(AnalysisError::function_not_found(
@@ -219,7 +224,7 @@ impl Analyser {
                 let result_type = match resolved_operation {
                     Binding::Resolved(res) => {
                         if let StaticType::Function { return_type, .. } =
-                            self.scope_tree.get_type(*res)
+                            self.scope_tree.get_type(res.var)
                         {
                             Some(return_type.as_ref().clone())
                         } else {
@@ -256,15 +261,15 @@ impl Analyser {
                                 ..
                             } = &value.expression
                             {
-                                let container_type = self.scope_tree.get_type(*target).clone();
+                                let container_type = self.scope_tree.get_type(target.var).clone();
                                 if let Some(elem_type) = container_type.index_element_type() {
                                     let widened_elem = elem_type.lub(&result_type);
                                     if widened_elem != elem_type {
                                         let new_container =
                                             container_type.with_element_type(widened_elem);
                                         let _ = self
                                             .scope_tree
-                                            .update_binding_type(*target, new_container);
+                                            .update_binding_type(target.var, new_container);
                                     }
                                 }
                             }
@@ -405,14 +410,19 @@ impl Analyser {
             Expression::Call {
                 function,
                 arguments,
+                operator_form,
             } => {
                 let mut type_sig = Vec::with_capacity(arguments.len());
                 for a in arguments {
                     type_sig.push(self.analyse_or_any(a));
                 }
 
-                let callee_type =
-                    self.resolve_function_with_argument_types(function, &type_sig, *span);
+                let callee_type = self.resolve_function_with_argument_types(
+                    function,
+                    &type_sig,
+                    *operator_form,
+                    *span,
+                );
 
                 let StaticType::Function { return_type, .. } = callee_type else {
                     if callee_type == StaticType::Any {
@@ -483,6 +493,7 @@ impl Analyser {
         &mut self,
         ident: &mut ExpressionLocation,
         argument_types: &[StaticType],
+        operator_form: bool,
         span: Span,
     ) -> StaticType {
         let ExpressionLocation {
@@ -497,7 +508,7 @@ impl Analyser {
 
         let binding = self
             .scope_tree
-            .resolve_function_binding(name, argument_types);
+            .resolve_function_binding(name, argument_types, operator_form);
 
         let out_type = match &binding {
             Binding::None => {
@@ -508,20 +519,35 @@ impl Analyser {
                 ));
                 return StaticType::Any;
             }
-            Binding::Resolved(res) => self.scope_tree.get_type(*res).clone(),
-
-            Binding::Dynamic(_) => {
-                // Dispatch is decided at runtime, so we have no sound static bound
-                // on the result. The runtime may pick a declared overload or fall
-                // through to elementwise (vectorized) dispatch, which can produce
-                // a value no declared overload returns — treating the LUB of
-                // declared returns as the result type is unsound and led to issue
-                // #139, where `let diff = a - b` over tuples was inferred as
-                // `Number` and a follow-up `diff * diff` then matched the numeric
-                // overload directly and bypassed dynamic dispatch entirely.
+            Binding::Resolved(candidate) => {
+                let return_type = candidate_return(&self.scope_tree, candidate, argument_types);
+                let scalar_type = self.scope_tree.get_type(candidate.var).clone();
+                // Preserve `parameters` from the underlying scalar so any
+                // downstream consumer that inspects the function shape sees
+                // the original arity; only the return type changes for vec.
+                match scalar_type {
+                    StaticType::Function { parameters, .. } => StaticType::Function {
+                        parameters,
+                        return_type: Box::new(return_type),
+                    },
+                    _ => StaticType::Any,
+                }
+            }
+            Binding::Dynamic(candidates) => {
+                // Runtime decides which candidate fires. LUB across every
+                // candidate's inferred return type — scalars contribute their
+                // declared return, vecs contribute `Tuple<elem_return; max_len>`.
+                // `LUB(Tuple<...>, scalar) = Any` in the type lattice, so the
+                // mixed case naturally falls to Any; pure-scalar Dynamic
+                // recovers the precision PR #140 had to pessimise.
+                let return_type = candidates
+                    .iter()
+                    .map(|c| candidate_return(&self.scope_tree, c, argument_types))
+                    .reduce(|a, b| a.lub(&b))
+                    .unwrap_or(StaticType::Any);
                 StaticType::Function {
                     parameters: None,
-                    return_type: Box::new(StaticType::Any),
+                    return_type: Box::new(return_type),
                 }
             }
         };
@@ -530,7 +556,52 @@ impl Analyser {
 
         out_type
     }
+}
+
+/// Returns the type a single candidate would produce for this call.
+///
+/// Examples (assume `+(Int, Int) -> Int` is the underlying scalar):
+/// - scalar candidate, call args `[Int, Int]` → `Int`
+/// - vec candidate, call args `[Tuple<Int, Int>, Tuple<Int, Int>]` →
+///   `Tuple<Int, Int>` (two element calls, each returns `Int`)
+/// - vec candidate, call args `[Tuple<Int, Int>, Int]` →
+///   `Tuple<Int, Int>` (the scalar `Int` broadcasts)
+/// - vec candidate, call args `[Any, Any]` → `Any` (no tuple length
+///   visible at compile time, so we can't say how long the result is)
+fn candidate_return(
+    scope_tree: &ScopeTree,
+    candidate: &Candidate,
+    argument_types: &[StaticType],
+) -> StaticType {
+    let StaticType::Function { return_type, .. } = scope_tree.get_type(candidate.var) else {
+        return StaticType::Any;
+    };
+    let scalar_return = return_type.as_ref().clone();
+    if !candidate.vectorized {
+        return scalar_return;
+    }
+    match static_vec_axis_len(argument_types) {
+        Some(len) => StaticType::Tuple(vec![scalar_return; len]),
+        None => StaticType::Any,
+    }
+}
 
+/// Length of the first tuple-shaped argument, which is how many element
+/// calls a vec dispatch will make.
+///
+/// Examples:
+/// - `[Tuple<Int, Int>, Int]` → `Some(2)`
+/// - `[Int, Tuple<Int, Int, Int>]` → `Some(3)`
+/// - `[Int, Int]` → `None` (vec doesn't apply)
+/// - `[Any, Any]` → `None` (we can't tell at compile time)
+fn static_vec_axis_len(sig: &[StaticType]) -> Option<usize> {
+    sig.iter().find_map(|t| match t {
+        StaticType::Tuple(elems) if !elems.is_empty() => Some(elems.len()),
+        _ => None,
+    })
+}
+
+impl Analyser {
     fn resolve_for_iterations(
         &mut self,
         iterations: &mut [ForIteration],
@@ -660,8 +731,16 @@ impl Analyser {
                 let get_args = [type_of_index_target.clone(), index_type.clone()];
                 let set_args = [type_of_index_target.clone(), index_type, StaticType::Any];
 
-                *resolved_get = Some(self.scope_tree.resolve_function_binding("[]", &get_args));
-                *resolved_set = Some(self.scope_tree.resolve_function_binding("[]=", &set_args));
+                // Index syntax is not operator-form for vec purposes — there is no
+                // natural element-wise broadcast story for `(list_a, list_b)[i]`.
+                *resolved_get = Some(
+                    self.scope_tree
+                        .resolve_function_binding("[]", &get_args, false),
+                );
+                *resolved_set = Some(
+                    self.scope_tree
+                        .resolve_function_binding("[]=", &set_args, false),
+                );
 
                 if let Some(t) = type_of_index_target.index_element_type() {
                     Ok(t)