docs(overload): document default return selection

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

5 files changed, 21 insertions, 9 deletions

diff --git a/AGENTS/CONVENTIONS/CALLS.md b/AGENTS/CONVENTIONS/CALLS.md
index 55b3647..df3d61d 100644
--- a/AGENTS/CONVENTIONS/CALLS.md
+++ b/AGENTS/CONVENTIONS/CALLS.md
@@ -29,7 +29,7 @@ bridge C void* and nominal pseudocode pointer types.
   prototypes are pre-registered too.
 - 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,
+  An expression's expected result type filters overloads when present. Without a result context, a DEFAULT return resolves return-only ambiguity within one name and canonical parameter signature. Overload sets,
   visibility filtering and exact selection:
   [SUBSYSTEMS/FUNCTIONS.md](../SUBSYSTEMS/FUNCTIONS.md#signatures-and-call-resolution).
 - `emitPrototype` rejects builtin and enum names. Ordinary non-EXTERN, non-OVERLOAD
diff --git a/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md b/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md
index 6c869cf..79f1a88 100644
--- a/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md
+++ b/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md
@@ -45,7 +45,7 @@ Part of [Load-bearing conventions](../CONVENTIONS.md). Basic call resolution is
 - Both getExprTypeInfo and emission must consult this resolver with the expression's
   result context before hardcoded builtin result types. A strict context requires the
   overload's return type to match exactly; a cast only prefers it; without a context,
-  return-only-distinct candidates are ambiguous. Returns may be any supported function
+  return-only-distinct candidates need a unique DEFAULT return. Defaults never resolve parameter-signature or global/member ties. Returns may be any supported function
   result, including non-BOOLEAN comparisons/logic. emitCoercedExpr still rejects a
   direct STRING to BOOLEAN conversion; CASE requires BOOLEAN comparisons.
 - Operators use shared argument marshalling and exception-aware calls. Member
diff --git a/AGENTS/PITFALLS/core-language.md b/AGENTS/PITFALLS/core-language.md
index 5018fb3..05793e7 100644
--- a/AGENTS/PITFALLS/core-language.md
+++ b/AGENTS/PITFALLS/core-language.md
@@ -32,8 +32,8 @@ source, most also by compiling and running test programs.
 - **`/` always yields REAL** (double FDiv), even for two INTEGERs; integer division is
   DIV/MOD only.
   - CHR returns CHAR, not STRING; CHR(0) is a NUL CHAR that converts to a one-byte STRING.
-  - STR_TO_NUM always returns REAL and shares parseNumber (strtod, full consumption, overflow rejected, only `0-9 . e E + -` after leading whitespace, so no nan/inf/hex) with IS_NUM and INPUT REAL (`__cps_parse_real` in InputGen.cc); change them together.
-  - NUM_TO_STR keeps the full signed i64 range for INTEGER; REAL uses the shortest
+  - STR_TO_NUM defaults to REAL and shares parseNumber (strtod, full consumption, overflow rejected, only `0-9 . e E + -` after leading whitespace, so no nan/inf/hex) with IS_NUM and INPUT REAL (`__cps_parse_real` in InputGen.cc); change them together. Its INTEGER overload applies INT to the parsed REAL, inheriting REAL rounding and truncating toward zero with a range check.
+  - NUM_TO_STR defaults to STRING; its CHAR overload uses the same text and requires length 1. It keeps the full signed i64 range for INTEGER; REAL uses the shortest
     round-trip text (realText in string.cc), byte-identical to OUTPUT's IR helper in
     OutputGen.cc (`__cps_output_real`); change both together. C_DOUBLE output keeps `%f`.
 - **`getExprTypeInfo` returns nullptr** for expressions it can't classify (null-check
diff --git a/AGENTS/PITFALLS/overload-template-operator.md b/AGENTS/PITFALLS/overload-template-operator.md
index f4a52ad..909e5f7 100644
--- a/AGENTS/PITFALLS/overload-template-operator.md
+++ b/AGENTS/PITFALLS/overload-template-operator.md
@@ -13,7 +13,11 @@ Part of the [pitfalls index](../PITFALLS.md).
   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.
+  context, return-only-distinct candidates need one DEFAULT return or remain ambiguous.
+  DEFAULT never resolves competing parameter signatures.
+- Each name and canonical parameter signature permits only one DEFAULT return,
+  including across invisible units; different parameter signatures may each have
+  their own. Only non-VOID OVERLOAD functions accept RETURNS DEFAULT.
 - 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
@@ -33,7 +37,8 @@ Part of the [pitfalls index](../PITFALLS.md).
 - 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,
-  specialization, bare injected class name, pointer-alias templates. Pointer-linked
+  specialization, bare injected class name, pointer-alias templates, DEFAULT
+  returns (including methods in class templates). Pointer-linked
   generic containers remain unsupported; use fixed fields or other supported value
   layouts.
 - Class instances follow ordinary constructor rules, so a parameterized NEW alone does
@@ -53,7 +58,8 @@ Part of the [pitfalls index](../PITFALLS.md).
 - Exact matching considers visible globals and left-class members together, and the
   result type joins the match when the context supplies one; ties are errors,
   including private/public ties. Without a context, return-only-distinct candidates
-  are ambiguous; casts only prefer their target type.
+  need a unique DEFAULT return or remain ambiguous; defaults do not resolve
+  global/member ties, and casts only prefer their target type.
 - Comparison and logic result types are declared, not assumed BOOLEAN; a strict
   BOOLEAN context requires an overload returning BOOLEAN. CASE comparisons must return
   BOOLEAN. AND/OR overloads evaluate both operands.
diff --git a/AGENTS/SUBSYSTEMS/FUNCTIONS.md b/AGENTS/SUBSYSTEMS/FUNCTIONS.md
index 134ee8b..9555f1d 100644
--- a/AGENTS/SUBSYSTEMS/FUNCTIONS.md
+++ b/AGENTS/SUBSYSTEMS/FUNCTIONS.md
@@ -29,8 +29,14 @@ internal __cps_main).
   overload-set map (`FunctionGen::getOverloads`, filtered by unit visibility).
 - `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.
+  a cast only prefers it. Without a context, return-only-distinct candidates use
+  the unique DEFAULT return, otherwise they are ambiguous. A single ordinary definition keeps implicit conversions.
+- `RETURNS DEFAULT type` records IsDefaultReturn on PrototypeAST and FuncSig.
+  Only non-VOID OVERLOAD functions support it; templates reject it. Registration
+  rejects two defaults for one name and ParamKey across all input units.
+  FunctionGen::selectDefaultReturn is shared by call and operator resolution; it
+  only resolves candidates with the same name and ParamKey, preserving parameter
+  ambiguity and global/member ties. Defaults do not affect link names.
 - 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.