feat(overload): select overloads by return type as well as parameters

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

2 files changed, 23 insertions, 12 deletions

diff --git a/AGENTS/PITFALLS/overload-template-operator.md b/AGENTS/PITFALLS/overload-template-operator.md
index b7c139e..6f23238 100644
--- a/AGENTS/PITFALLS/overload-template-operator.md
+++ b/AGENTS/PITFALLS/overload-template-operator.md
@@ -6,12 +6,16 @@ Part of the [pitfalls index](../PITFALLS.md).
 
 - OVERLOAD is reserved and prefixes FUNCTION/PROCEDURE (after PUBLIC/PRIVATE for
   methods). Every same-name definition must opt in.
-- Only count, canonical parameter types and array rank distinguish signatures: return
-  type, BYREF/BYVAL and array bounds do not.
+- Count, canonical parameter types, array rank and (for non-VOID definitions) return
+  type distinguish signatures; a PROCEDURE counts as VOID. BYREF/BYVAL and array
+  bounds do not.
 - Calls match exact static types, even for a single OVERLOAD definition; ordinary
-  functions still coerce arguments.
-- Call visibility filters the set, but duplicate signatures conflict across all
-  inputs. MAIN and builtins cannot be overloaded.
+  functions still coerce arguments. A known expected result type (assignment, BYVAL
+  argument, RETURN, condition, subscript, CASE comparison) must match the overload's
+  return type exactly; `(T) x` only prefers T and otherwise converts. Without a
+  context, return-only-distinct candidates are ambiguous.
+- Call visibility filters the set, but duplicate signatures (parameters and return
+  type) conflict across all inputs. MAIN and builtins cannot be overloaded.
 - NEW supports overloads; DECLARE, fields and arrays needing default construction
   require a matching no-argument NEW.
 - Private access is checked after selection, never used to select a public fallback.
diff --git a/AGENTS/SUBSYSTEMS/FUNCTIONS.md b/AGENTS/SUBSYSTEMS/FUNCTIONS.md
index 0297c48..4983853 100644
--- a/AGENTS/SUBSYSTEMS/FUNCTIONS.md
+++ b/AGENTS/SUBSYSTEMS/FUNCTIONS.md
@@ -26,14 +26,21 @@ canonical parameter list (MAIN uses internal __cps_main).
 
 - `emitPrototype` records each function's pseudocode signature in a `FuncSig`
   overload-set map (`FunctionGen::getOverloads`, filtered by unit visibility).
-- `resolveCall` selects exact static parameter types/ranks for OVERLOAD, while a single
-  ordinary definition keeps implicit conversions.
-- Parameter keys exclude return types, modes and bounds (they never distinguish
-  overloads); equivalent C aliases use
-  CIdentity. Every same-name definition must be OVERLOAD; duplicate keys fail even
-  across invisible units.
+- `resolveCall` selects exact static parameter types/ranks for OVERLOAD. When the call
+  site has an expected result type, the candidate must also return exactly that type;
+  a cast only prefers it. Without a context, return-only-distinct candidates are
+  ambiguous. A single ordinary definition keeps implicit conversions.
+- Parameter keys exclude return types, modes and bounds; the separate ReturnKey holds
+  the declared result (PROCEDURE is VOID). Equivalent C aliases use CIdentity.
+  Duplicate signatures require both keys to match, even across invisible units.
+- CodeGen records result contexts per expression node before the first type query
+  (`expectResult`/`resultContext`); assignment, BYVAL/RETURN, coercion and cast sites
+  register them, and call/operator selection consults the same table for typing and
+  emission.
 - FunctionGen tracks prototype registration separately from source names and indexes
-  signatures by LLVM link name for RETURN (`getSignatureByLink`).
+  signatures by LLVM link name for RETURN (`getSignatureByLink`). A non-VOID
+  OVERLOAD link name appends `:ReturnKey` after `Name(ParamKey)`; PROCEDURE, NEW and
+  OPERATOR<- keep their old names.
 - `CodeGen::marshalCallArgs` consumes the selected FuncSig, and `getExprTypeInfo`
   resolves the same calls without emitting IR.
 - Prototype pre-registration (calls may precede definitions): see