docs(vectorization): reconcile RFC with shipped implementation 📐

Status flipped from Draft to Implemented. Patched the sections that
drifted from what landed:

- Worked-example commentary no longer claims the compiler emits
  unrolled element calls — that's RFC step 6, still deferred.
- Type-inference table now reflects the actual mechanism (LUB across
  all candidates' inferred returns) instead of the separate "all
  scalar" vs "any vec" branches; documents the uniform LUB-collapse
  on vec return types and the exact-subtype precedence step.
- Runtime broadening describes the new `find_overload`/
  `dispatch_vec_call` path instead of the deleted try_vectorized_call.
- Implementation checklist marked done per step with a ⏸ on step 6.
- Open questions resolved or annotated with what shipped (LUB collapse
  over per-position, "no function found" over a dedicated arity error,
  empty tuple rejects, etc.).
- References updated to point at the current code (and PR #141).

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

Author: timfennis

docs/design/vectorization.md

@@ -1,6 +1,11 @@
 # RFC: Vectorization scope
 
-Status: Draft. Refine before implementing.
+Status: Implemented in PR [#141] (commits `df7b11b`, `e367145`). RFC steps
+1–5 and 7 shipped together; step 6 (compiler unrolling of `Resolved` vec
+candidates) is deferred — see the [Compiler optimisation](#compiler-optimisation)
+section.
+
+[#141]: https://github.com/timfennis/andy-cpp/pull/141
 
 ## Summary
 
@@ -106,6 +111,16 @@ A vec candidate matches the call's arguments when:
 - Each per-position element matches the underlying scalar overload's
   parameter type. Scalar args in non-tuple positions broadcast.
 
+Static and runtime checks differ in how they realise the per-position
+rule. The analyser collapses each tuple-shaped arg to the LUB of its
+element types (so `Tuple<Int, Float>` becomes `Number` for the lookup
+sig) and then queries the existing overload-resolution helpers
+(`find_function` for exact-subtype, `find_function_candidates` for
+loose). The runtime checks every element pair individually against the
+scalar's parameter types — that's what catches mixed-element tuples
+like `(1, "a") + (2, "b")` that today's probe-first dispatch crashes
+on at element 1.
+
 This search space drives both `Resolved` and `Dynamic` bindings:
 
 - If the analyser can pin exactly one candidate at compile time (the
@@ -130,8 +145,12 @@ Worked examples on the search space above:
 
 The `(1, 2) + (3, 4)` row is the case worth highlighting. Both arg
 types are statically `Tuple<Int, Int>`, so the analyser picks vec
-candidate #4 at compile time. The compiler emits the unrolled element
-calls directly. No OverloadSet construction, no runtime lookup.
+candidate #4 at compile time. Once the [compiler unrolling
+optimisation](#compiler-optimisation) lands, this case emits unrolled
+element calls directly with no `OverloadSet` construction. As shipped
+the candidate is pushed via a single-entry overload set and dispatched
+through the same value-level path Dynamic uses; the analyser-side win
+is the precise `Tuple<Int, Int>` result type.
 
 The Any rows are where `Dynamic` shows up: the analyser cannot narrow
 the search space, so it carries the candidate list forward and lets the
@@ -151,14 +170,21 @@ dispatches over the same list the analyser produced.
 
 ### Runtime broadening
 
-Three changes to `try_vectorized_call` in `ndc_vm/src/vm.rs`:
+`try_vectorized_call` is gone. `find_overload` walks the augmented
+candidate list once and routes the call:
 
-1. Drop the `args != 2` guard. Vec applies for any arity.
-2. Replace `as_numeric_tuple` (requires `is_number()` on every element)
-   with a plain `Object::Tuple` shape check. Element-call dispatch
-   handles the type lookup.
-3. Settle the n-ary broadcast rule: any tuple-shaped arg defines the
-   axis; all tuples must have equal length; scalars broadcast.
+- Scalar candidate: `Function::matches_value_args` checks the args
+  directly; success returns `Callable::Scalar(func)`.
+- Vec candidate: every element pair must satisfy the underlying scalar's
+  parameter types (not just the first pair — the old probe-based
+  dispatch silently miscoupled mixed-type tuples). Success returns
+  `Callable::Vec(scalar_fn)`, which `dispatch_vec_call` invokes once per
+  axis position, broadcasting non-tuple args.
+
+The n-ary broadcast rule: any tuple-shaped arg defines the axis; all
+tuple-shaped args must have equal length; scalars broadcast. Empty
+tuples and length mismatches decline the vec match and the call falls
+through to the regular "no overload found" error.
 
 After these changes:
 
@@ -196,15 +222,31 @@ Type inference per binding shape:
 | binding                                  | result type                                |
 |------------------------------------------|--------------------------------------------|
 | `Resolved` to a scalar candidate         | overload's declared return                 |
-| `Resolved` to a vec candidate            | `Tuple<elem_return, …>`                    |
-| `Dynamic`, all candidates scalar         | LUB of declared returns (PR #140 recovery) |
-| `Dynamic`, any candidate vectorized      | `Any`                                      |
-
-`Dynamic` whose candidate list contains only scalars happens for
-regular calls and for operator calls whose args are statically
-non-tuple, non-Any. These recover the LUB precision PR #140
-pessimised. `Dynamic` lists that mix scalars with vec variants stay at
-`Any` because runtime dispatch can pick either kind.
+| `Resolved` to a vec candidate            | `Tuple<elem_return; max_len>`              |
+| `Dynamic`                                | LUB across every candidate's inferred return |
+
+The analyser computes each candidate's contribution (declared return
+for scalars, `Tuple<elem_return; max_len>` for vecs where `max_len` is
+the statically known broadcast axis) and LUBs them. In the all-scalar
+case this recovers the LUB precision PR #140 had to pessimise. In the
+mixed-candidate case the type lattice naturally collapses
+`LUB(Tuple<…>, scalar)` to `Any` because tuples only join with tuples
+of equal arity — no special-casing needed.
+
+Vec candidate return type uses **uniform LUB collapse**: each tuple-arg
+contributes the LUB of its element types in a single position, and the
+result tuple is filled with the scalar overload's return repeated
+`max_len` times. So `(Int, Float) + (Float, Int)` → `Tuple<Number,
+Number>`, not the per-element-precise `Tuple<Int, Number>`. The
+per-position alternative was considered (see [Alternatives](#alternatives-considered))
+and rejected for simplicity.
+
+Vec candidate resolution mirrors the scalar path's two-stage lookup:
+an exact-subtype `find_function` hit on the synthetic sig wins over
+the looser `find_function_candidates` set. This is what makes
+`Tuple<Int, Int> - Tuple<Int, Int>` resolve to `Tuple<Int, Int>`
+instead of LUB'ing every compatible `-` overload into `Tuple<Number,
+Number>`.
 
 ### Compiler optimisation
 
@@ -220,32 +262,34 @@ instead of `OverloadSet` dispatch:
 ```
 
 The unrolled path skips OverloadSet construction and runtime dispatch.
-This optimisation is independent of correctness; it lands after the
-soundness work.
+This optimisation is independent of correctness; it has not yet landed.
+As shipped, `Resolved(vec)` flows through a single-entry overload set
+and the same dispatch path as `Dynamic`.
 
 ## Implementation
 
-Each step can land on its own:
-
-1. Parser: add `operator_form: bool` to `Expression::Call`. Plumb
-   through `Clone`/`Debug`.
-2. Scope: synthesise vec candidates into the candidate list when
-   `operator_form` is true. Carry the `vectorized` flag on each
-   candidate.
-3. Runtime: drop the arity-2 and numeric-element guards; replace
-   `try_vectorized_call` with vec-candidate dispatch inside
-   `find_overload`. Settle n-ary broadcast.
-4. Runtime: error-wrap element-call failures with "while vectorising
-   `<call>` at index N".
-5. Analyser: type-infer per the binding-shape table. Recover LUB when
-   the candidate list contains only scalars.
-6. Compiler: emit the unrolled path when `Resolved` points to a vec
-   candidate.
-7. Delete `BinaryOperator::supports_vectorization` (dead code under
-   this design).
-
-Steps 1-4 form a "broadening" PR. Steps 5-6 form a "precision
-recovery" PR. Step 7 stands alone.
+Steps 1–5 and 7 shipped together as one PR. Step 6 is deferred.
+
+1. ✅ Parser: `operator_form: bool` added to `Expression::Call`. Derived
+   `Clone`/`Debug` propagate it automatically.
+2. ✅ Scope: vec candidates synthesised via a per-position LUB-collapsed
+   sig when `operator_form` is true. Both the loose-compatibility set
+   and the exact-subtype match are tracked so `Resolved(vec)` mirrors
+   `Resolved(scalar)`'s precision.
+3. ✅ Runtime: `try_vectorized_call` removed; vec dispatch lives in
+   `find_overload` and `dispatch_vec_call`. N-ary broadcast settled
+   (any tuple-shaped arg defines the axis; equal-length required;
+   non-tuple args broadcast).
+4. ✅ Runtime: element-call failures wrapped with `"while vectorising
+   '<name>' at index N"`.
+5. ✅ Analyser: type inference produces per-candidate types and LUBs
+   them, recovering scalar LUB precision and giving precise tuple
+   types for `Resolved(vec)`.
+6. ⏸ Compiler: unrolled emission for `Resolved(vec)` not yet
+   implemented. Today the analyser-side win (precise return type) lands;
+   the runtime still dispatches through the overload-set path.
+7. ✅ `BinaryOperator::supports_vectorization` and the
+   `StaticType::supports_vectorization{,_with}` helpers deleted.
 
 ## Alternatives considered
 
@@ -273,55 +317,54 @@ operator names are special.
 
 ## Open questions
 
-### P1: silent semantic shift on operator overloads
+### P1: silent semantic shift on operator overloads — open
 
-Adding `fn +(t: Tuple, u: Tuple) -> X` shifts `(1, 2) + (3, 4)` from
-vec to first-class dispatch. The hazard is bounded to operator
+Adding `fn +(t: Tuple, u: Tuple) -> X` would shift `(1, 2) + (3, 4)`
+from vec to first-class dispatch. The hazard is bounded to operator
 overloads because regular calls never vec. The set of operator names
-is small, fixed, and known to the parser.
-
-Mitigations to pick from later:
-
-- Stdlib discipline on operator overloads.
-- Compiler warning on `Tuple`-typed operator parameters.
-
-### P2: element-call errors lose outer-call context
+is small, fixed, and known to the parser. No mitigation shipped;
+stdlib discipline is the de-facto safeguard for now.
 
-`(1, "a") + (2, "b")` errors statically today. Under broadening it
-errors at element 1 with "no `+` for (String, String)". The outer call
-site disappears from the error.
+### P2: element-call errors lose outer-call context — resolved
 
-Mitigation: error-wrap during vec-candidate invocation (step 4 of
-Implementation).
+Element-call failures are now wrapped with `"while vectorising
+'<name>' at index N: <inner>"`, so the outer call name and the failing
+index appear in the error message.
 
-### Length mismatch error
+### Length mismatch error — accepted as "no function found"
 
-`(1, 2, 3) + (4, 5)` should error with "vec arity mismatch", not "no
-function found".
+`(1, 2, 3) + (4, 5)`: the vec candidate match declines (length
+mismatch on the tuple axis) and the call falls through to the regular
+`"no function called '+' found matches the arguments: (Tuple<Int, Int,
+Int>, Tuple<Int, Int>)"` error. A dedicated `"vec arity mismatch"`
+message would be friendlier but isn't required for correctness.
 
-### Empty tuple
+### Empty tuple — errors as recommended
 
-`() + ()`: error or return `()`. Recommendation: error.
+`() + ()`: `synthetic_vec_sig` rejects empty tuples, so no vec
+candidate is synthesised. The call falls through to `"no function
+found"` rather than returning `()`.
 
-### Per-position scalar resolution for vec candidates
+### Per-position scalar resolution for vec candidates — resolved (LUB collapse)
 
-`(Int, Float) + (Float, Int)`: each element pair matches a different
-scalar overload. The synthesised vec variant points to a single scalar
-candidate; one variant won't cover both pairs. Options: synthesise a
-per-position vec candidate (precise tuple type, larger candidate list),
-or accept that mixed-element-type cases fall to a less precise
-`Tuple<Number, …>` via `Dynamic` dispatch.
+`(Int, Float) + (Float, Int)` resolves to a single vec candidate via
+per-position LUB, so the result type is `Tuple<Number, Number>` rather
+than the per-element-precise `Tuple<Int, Number>`. The precision loss
+only affects operator-form calls over genuinely heterogeneous tuples,
+which in practice are rare (product-style tuples like `("Tim", 35,
+"NL")` never trigger vec at all), so the candidate-list simplicity won
+out. Revisit if the imprecision starts to bite.
 
-### Unrolling ceiling
+### Unrolling ceiling — pending
 
-At what tuple size does compile-time unrolling stop being worth the
-bytecode bloat? Pick a threshold (suggested N ≤ 8). Confirm with bench
-data.
+Relevant once step 6 (compiler unrolling) lands. Suggested threshold
+N ≤ 8; confirm with bench data when implementing.
 
 ## References
 
 - Issue [#139]: original regression.
 - PR [#140]: soundness fix (`Binding::Dynamic` → `Any`).
-- `ndc_vm/src/vm.rs::try_vectorized_call`: current vec implementation.
-- `ndc_parser/src/operator.rs::BinaryOperator::supports_vectorization`:
-  dead predicate, deletable under this design.
+- PR [#141]: implementation of this RFC.
+- `ndc_vm/src/vm.rs::dispatch_vec_call`: runtime vec dispatch.
+- `ndc_analyser/src/scope.rs::synthetic_vec_sig`: per-position LUB sig
+  used for static vec candidate lookup.