feat(operator): select operator overloads by the expected result type

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

2 files changed, 13 insertions, 9 deletions

diff --git a/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md b/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md
index 7177b23..f7ebd78 100644
--- a/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md
+++ b/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md
@@ -40,10 +40,12 @@ Part of [Load-bearing conventions](../CONVENTIONS.md). Basic call resolution is
 - `OperatorGen.cc` probes visible global and left-class member signatures without
   emitting diagnostics or evaluating operands. Matching is exact; member/global ties
   are ambiguous and access is checked only after selection.
-- Both getExprTypeInfo and emission must consult this resolver before hardcoded
-  builtin result types. Returns may be any supported function result, including
-  non-BOOLEAN comparisons/logic. emitCoercedExpr rejects implicit STRING to BOOLEAN;
-  CASE separately requires BOOLEAN comparisons.
+- 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
+  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
   lvalues keep their original address; rvalues are materialized with Alive tracking
   and destroyed at statement end.
diff --git a/AGENTS/PITFALLS/overload-template-operator.md b/AGENTS/PITFALLS/overload-template-operator.md
index 6f23238..5718b2d 100644
--- a/AGENTS/PITFALLS/overload-template-operator.md
+++ b/AGENTS/PITFALLS/overload-template-operator.md
@@ -50,11 +50,13 @@ Part of the [pitfalls index](../PITFALLS.md).
 
 - Unary/binary operators require OVERLOAD FUNCTION, with supported arity and at least
   one record/class/enum operand. Pointer aliases alone do not qualify.
-- Exact matching considers visible globals and left-class members together; ties are
-  errors, including private/public ties.
-- Comparison and logic result types are declared, not assumed BOOLEAN; implicit
-  STRING to BOOLEAN is rejected. CASE comparisons must return BOOLEAN. AND/OR
-  overloads evaluate both operands.
+- 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.
+- 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.
 - Temporary member receivers are destroyed at statement end, including exception
   exits; ordinary DECLARE objects remain function-scoped.
 - Explicit calls use OPERATOR+(a,b) or a.OPERATOR+(b).