docs(overload): document return-type selection across keyword pages

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

6 files changed, 21 insertions, 12 deletions

diff --git a/AGENTS/CONVENTIONS/CALLS.md b/AGENTS/CONVENTIONS/CALLS.md
index 1942ded..3fc2daa 100644
--- a/AGENTS/CONVENTIONS/CALLS.md
+++ b/AGENTS/CONVENTIONS/CALLS.md
@@ -27,9 +27,11 @@ bridge C void* and nominal pseudocode pointer types.
   pre-pass) before statement emission, so call-before-definition is fine; a call with
   no registered signature is a compile error (no extern is fabricated). Method
   prototypes are pre-registered too.
-- OVERLOAD signatures append canonical parameter types to the link name; ordinary
-  names except MAIN get no mangling. Overload sets, visibility filtering and exact
-  selection: [SUBSYSTEMS/FUNCTIONS.md](../SUBSYSTEMS/FUNCTIONS.md#signatures-and-call-resolution).
+- OVERLOAD link names append canonical parameter types, plus `:ReturnKey` for non-VOID
+  results (NEW and OPERATOR<- excepted); ordinary names except MAIN get no mangling.
+  An expression's expected result type filters overloads when present. Overload sets,
+  visibility filtering and exact selection:
+  [SUBSYSTEMS/FUNCTIONS.md](../SUBSYSTEMS/FUNCTIONS.md#signatures-and-call-resolution).
 - In all cases, `emitPrototype` rejects names that collide with runtime/libc symbols
   (`isReservedRuntimeName`), builtins, or enum values. Signatures retain the first
   declaration spelling for LLVM lookup, independently of call-site casing.
diff --git a/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md b/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md
index f7ebd78..6c869cf 100644
--- a/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md
+++ b/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md
@@ -22,7 +22,9 @@ Part of [Load-bearing conventions](../CONVENTIONS.md). Basic call resolution is
 - When multiple definitions share a function/procedure name, every ordinary and
   template definition must specify OVERLOAD.
 - `resolveCall` computes static argument types/ranks once, then tries exact ordinary,
-  non-variadic template and variadic template tiers; same-tier ties are errors.
+  non-variadic template and variadic template tiers; an expected result type filters
+  ordinary candidates, while template tiers still match parameters only. Same-tier ties
+  are errors.
 - Candidate checking must stay silent and must not instantiate speculative class
   types. Explicit arguments pre-bind types without allowing conversions.
 - Instances keep the template owner for diagnostics/library behavior and the first
diff --git a/AGENTS/PITFALLS/overload-template-operator.md b/AGENTS/PITFALLS/overload-template-operator.md
index 5718b2d..f4a52ad 100644
--- a/AGENTS/PITFALLS/overload-template-operator.md
+++ b/AGENTS/PITFALLS/overload-template-operator.md
@@ -28,8 +28,8 @@ Part of the [pitfalls index](../PITFALLS.md).
   Deduction recognizes T and array element T, never the T inside Box<T>.
 - When multiple ordinary/template functions share a name, every definition must
   specify OVERLOAD; exact ordinary definitions win, then non-variadic templates, then
-  variadic templates, with same-tier ties ambiguous. Explicit arguments select
-  templates only.
+  variadic templates, with same-tier ties ambiguous. An expected result type filters
+  ordinary definitions but not templates. Explicit arguments select templates only.
 - Packs are final non-array parameters and expand only in call/constructor argument
   lists; pack fields are rejected, including in variadic classes.
 - Unsupported: non-type parameters, SIZEOF..., member/operator templates,
diff --git a/AGENTS/SUBSYSTEMS/CLASSES.md b/AGENTS/SUBSYSTEMS/CLASSES.md
index 65b1c69..21e5124 100644
--- a/AGENTS/SUBSYSTEMS/CLASSES.md
+++ b/AGENTS/SUBSYSTEMS/CLASSES.md
@@ -22,8 +22,8 @@ construction and destruction are in [class lifetime](CLASS_LIFETIME.md).
 
 - Class ASTs also own their `FunctionDefAST` methods. PrototypeAST retains the owner and
   access level; `getLinkName()` supplies the source key `Class.Method`.
-- FunctionGen appends `(canonical parameter types)` only for OVERLOAD, leaving ordinary
-  symbols unchanged.
+- FunctionGen appends `(canonical parameter types)` and, for non-VOID results, a
+  `:ReturnKey` suffix only for OVERLOAD, leaving ordinary symbols and NEW unchanged.
 - CodeGen registers methods separately in `ClassMethods` overload vectors and
   pre-registers their prototypes after the type pre-pass.
 - `resolveMethod` uses `resolveCall`; access is checked on the selected overload.
diff --git a/AGENTS/SUBSYSTEMS/FUNCTIONS.md b/AGENTS/SUBSYSTEMS/FUNCTIONS.md
index 4983853..134ee8b 100644
--- a/AGENTS/SUBSYSTEMS/FUNCTIONS.md
+++ b/AGENTS/SUBSYSTEMS/FUNCTIONS.md
@@ -6,7 +6,8 @@ Part of the [subsystem notes](../SUBSYSTEMS.md). See also [EXTERN "C"](EXTERN.md
 ## Functions (`FunctionGen`)
 
 Plain LLVM functions, external linkage, exact pseudocode name unless OVERLOAD appends a
-canonical parameter list (MAIN uses internal __cps_main).
+canonical parameter list and, for non-VOID results, a `:ReturnKey` suffix (MAIN uses
+internal __cps_main).
 
 ### Parameters and bodies
 
@@ -51,8 +52,10 @@ canonical parameter list (MAIN uses internal __cps_main).
 - PrototypeAST retains the operator token; FunctionGen validates operand count and
   requires a record/class/enum operand.
 - Global signatures and left-class methods share exact-type selection, used by
-  ValueTypeGen and ExpressionGen before builtin operations. Missing candidates leave
-  builtin rules intact; ties are errors. Member access is checked after selection.
+  ValueTypeGen and ExpressionGen before builtin operations and filtered by an expected
+  result type where present. A strict context whose operands match but whose result does
+  not sets `WrongResult`. Missing candidates leave builtin rules intact; ties are
+  errors. Member access is checked after selection.
 - The raw-expression argument-marshalling overload borrows AST pointers for operator
   calls; ordinary calls adapt their unique_ptr lists into it.
 - Member receivers use lvalue storage or a materialized, Alive-tracked temporary.
diff --git a/AGENTS/SUBSYSTEMS/TEMPLATES.md b/AGENTS/SUBSYSTEMS/TEMPLATES.md
index 444e816..95d2963 100644
--- a/AGENTS/SUBSYSTEMS/TEMPLATES.md
+++ b/AGENTS/SUBSYSTEMS/TEMPLATES.md
@@ -16,7 +16,9 @@ callable lookup.
 
 - `CodeGen::resolveCall` retains ordinary fast paths when no templates exist. Otherwise
   it computes static argument types and whole-array ranks once, selecting exact ordinary
-  definitions before non-variadic templates and then variadic templates.
+  definitions (including an expected result type when present) before non-variadic
+  templates and then variadic templates. Templates still match only substituted
+  parameter types; result contexts do not filter them.
 - Explicit type arguments pre-bind positional parameters and constrain a pack prefix;
   deduction from `T` or array element `T` fills remaining bindings. Composite types such
   as `Box<T>` are checked after substitution but do not deduce T.