feat(check): diagnose lambda return body vs declared mismatch

Phase 7-and-a-half added lambda return-type inference but
silently honored the declared annotation when present: an
`fn(x) -> bool: return "hi"` passed every check, because the
returning expression was never compared against the bool the user
promised. The mismatch surfaced only at the call site (if at all),
and pointed at the wrong span.

Extend the returnStack frame to carry an `expected` return type
alongside the collected types. push/pop already happens per fn /
lambda body; the expected slot is populated from `Typing.ReturnT`
at push time. recordReturn now checks against `expected` at the
return-statement's own span when the type is concrete (not
Dynamic / ErrorType - those would cascade false-positives).

walkFnDef participates too: a hoisted fn declared `-> bool` whose
body returns "hi" now fires at the return, not at every later
call site. Mirror behavior for nested fns - they push their own
frame, so an inner fn's returns check against the inner
declaration, not the outer's. The NestedFnReturnIsolated
snapshot pins this.

Multiple returns are each checked independently. A fn that
returns int from one branch and str from another, declared
`-> bool`, fires twice with two distinct spans - the user can
fix them one at a time.

Severity is Hint, matching the rest of the assignability checks.
Promotion to Error happens in the future severity migration once
literal types fill the remaining fidelity gaps.

Five new snapshot cases in fn_value/declared_return.snap plus
the renamed/repurposed LambdaDeclaredReturnMismatchFiresAtReturn
case in structural_match.snap (was Honored, marked the gap;
now closes it).

Author: amterp

rts/check/snapshots/fn_value/declared_return.snap

@@ -0,0 +1,99 @@
+### TITLE ###
+HoistedFnDeclaredReturnMismatchFires
+### DESCRIPTION ###
+A hoisted fn with a declared return type gets each `return E`
+checked against it. Mismatch fires at the return statement.
+### INPUT ###
+fn cb(x: int) -> bool:
+    return "hi"
+### STDOUT ###
+# Identifier types
+  (none)
+
+# Symbol types
+  cb (fn): fn(int) -> bool
+
+# Diagnostics
+  [hint] RAD30001 @ 2:5 - Return value of type 'str' is not assignable to declared return type 'bool'
+### TITLE ###
+HoistedFnMultipleReturnsEachChecked
+### DESCRIPTION ###
+Every return statement is checked independently. Both the int
+and the str disagree with the declared bool; both fire.
+### INPUT ###
+fn cb(x: int) -> bool:
+    if x > 0:
+        return 1
+    return "hi"
+### STDOUT ###
+# Identifier types
+  x @ 2:8 -> int
+
+# Symbol types
+  cb (fn): fn(int) -> bool
+  x (param): int
+
+# Diagnostics
+  [hint] RAD30001 @ 3:9 - Return value of type 'int' is not assignable to declared return type 'bool'
+  [hint] RAD30001 @ 4:5 - Return value of type 'str' is not assignable to declared return type 'bool'
+### TITLE ###
+HoistedFnReturnMatchesDeclared
+### DESCRIPTION ###
+When the return value matches the declaration, no diagnostic.
+This is the happy path.
+### INPUT ###
+fn cb(x: int) -> bool:
+    return x > 0
+### STDOUT ###
+# Identifier types
+  x @ 2:12 -> int
+
+# Symbol types
+  cb (fn): fn(int) -> bool
+  x (param): int
+
+# Diagnostics
+  (none)
+### TITLE ###
+HoistedFnDynamicReturnSuppresses
+### DESCRIPTION ###
+A return value that synth'd to Dynamic doesn't fire - we can't
+prove a mismatch from a "we don't know" type. Gradual-typing
+escape hatch.
+### INPUT ###
+fn dyn() -> any:
+    return 1
+
+fn cb(x: int) -> bool:
+    return dyn()
+### STDOUT ###
+# Identifier types
+  dyn @ 5:12 -> fn() -> any
+
+# Symbol types
+  cb (fn): fn(int) -> bool
+  dyn (fn): fn() -> any
+
+# Diagnostics
+  (none)
+### TITLE ###
+NestedFnReturnIsolated
+### DESCRIPTION ###
+A return inside a nested fn belongs to the nested fn, not the
+enclosing one. Here the outer fn declares `-> bool` but never
+returns; only the inner fn returns - it returns int, matching
+the inner declaration, so no diagnostic.
+### INPUT ###
+fn outer() -> bool:
+    fn inner() -> int:
+        return 5
+### STDOUT ###
+# Identifier types
+  (none)
+
+# Symbol types
+  inner (fn): fn() -> int
+  outer (fn): fn() -> bool
+
+# Diagnostics
+  (none)

rts/check/snapshots/fn_value/structural_match.snap

@@ -274,15 +274,13 @@ process(fn(x):
 # Diagnostics
   [hint] RAD30001 @ 4:9 - Argument type 'fn(any) -> void' is not assignable to expected type 'fn(int) -> bool'
 ### TITLE ###
-LambdaWithDeclaredReturnHonored
+LambdaDeclaredReturnMismatchFiresAtReturn
 ### DESCRIPTION ###
-When the user writes a return annotation (`-> bool`) we use it
-verbatim instead of inferring. Here the body returns "hi" (str),
-which doesn't match the declared bool - that's the right place
-for the diagnostic to fire (typed-local-style mismatch on the
-return, not at the call site). Today we don't yet enforce the
-body-vs-declared-return check, so the call still passes - this
-snapshot pins the current behavior and marks the gap.
+When the user writes a return annotation (`-> bool`) we honor it
+AND check each `return E` against it at the return statement's
+span (not at the call site). Here the body returns "hi" (str)
+where bool was promised - the diagnostic lands on the return,
+which is the right place to point the user.
 ### INPUT ###
 fn process(callback: fn(int) -> bool):
     callback(5)
@@ -298,4 +296,4 @@ process(fn(x) -> bool: return "hi")
   process (fn): fn(fn(int) -> bool)
 
 # Diagnostics
-  (none)
+  [hint] RAD30001 @ 4:31 - Return value of type 'str' is not assignable to declared return type 'bool'

rts/check/type_check.go

@@ -99,38 +99,59 @@ type typeChecker struct {
 	resolved *Resolved
 	info     *TypeInfo
 	frame    *Frame
-	// returnStack collects return-statement value types per
-	// enclosing function/lambda scope. Each entry is the running
-	// list of types observed inside one fn body. Lambdas use it to
-	// synth a proper TypingFnT return type instead of falling back
-	// to Dynamic. Pushed on lambda/fn entry, popped on exit. Stack
-	// depth N means we're inside N nested fn bodies; a return at
-	// depth N belongs to the innermost (top) frame, never the
-	// outer ones - matching the runtime where returns target the
-	// nearest enclosing fn.
-	returnStack [][]rl.TypingT
+	// returnStack carries one frame per enclosing function/lambda
+	// scope. `collected` accumulates return-value types for return
+	// inference (used by synthLambda; reserved for hoisted-fn
+	// inference). `expected` is the declared return type, used to
+	// check each `return E` at the return-statement's own span;
+	// nil means "no declared return, only inference applies."
+	// Pushed on lambda/fn entry, popped on exit.
+	returnStack []returnFrame
 }
 
-func (tc *typeChecker) pushReturnFrame() {
-	tc.returnStack = append(tc.returnStack, nil)
+type returnFrame struct {
+	collected []rl.TypingT
+	expected  rl.TypingT
+}
+
+func (tc *typeChecker) pushReturnFrame(expected rl.TypingT) {
+	tc.returnStack = append(tc.returnStack, returnFrame{expected: expected})
 }
 
 func (tc *typeChecker) popReturnFrame() []rl.TypingT {
 	n := len(tc.returnStack)
-	out := tc.returnStack[n-1]
+	out := tc.returnStack[n-1].collected
 	tc.returnStack = tc.returnStack[:n-1]
 	return out
 }
 
 // recordReturn appends a return-value type to the innermost fn
-// scope's accumulator. A return outside any fn (which is itself a
-// validation error caught elsewhere) is a no-op here.
-func (tc *typeChecker) recordReturn(t rl.TypingT) {
+// scope's accumulator and, if that scope has a declared return
+// type, checks the value against it at the return's own span. A
+// return outside any fn (validation-error elsewhere) is a no-op.
+func (tc *typeChecker) recordReturn(t rl.TypingT, retNode rl.Node) {
 	n := len(tc.returnStack)
 	if n == 0 {
 		return
 	}
-	tc.returnStack[n-1] = append(tc.returnStack[n-1], t)
+	tc.returnStack[n-1].collected = append(tc.returnStack[n-1].collected, t)
+	expected := tc.returnStack[n-1].expected
+	if expected == nil || retNode == nil || t == nil {
+		return
+	}
+	if isErrorType(t) || isDynamicLike(t) {
+		return
+	}
+	if expected.IsAssignableFrom(t) {
+		return
+	}
+	tc.info.Issues = append(tc.info.Issues, BindIssue{
+		Span:     retNode.Span(),
+		Severity: IssueHint,
+		Code:     rl.ErrTypeMismatch,
+		Message: fmt.Sprintf("Return value of type '%s' is not assignable to declared return type '%s'",
+			t.Name(), expected.Name()),
+	})
 }
 
 func (tc *typeChecker) walkFile(file *rl.SourceFile) {
@@ -183,7 +204,7 @@ func (tc *typeChecker) walkStmt(n rl.Node) {
 			}
 			t = rl.NewTupleType(elems...)
 		}
-		tc.recordReturn(t)
+		tc.recordReturn(t, v)
 	default:
 		// Generic descent. Later sub-commits replace these with
 		// kind-specific handlers (for loops, switch, return, etc.).
@@ -293,8 +314,14 @@ func (tc *typeChecker) walkFnDef(n *rl.FnDef) {
 	// collected types here yet - hoisted-fn return inference is a
 	// separate commit gated on SCC handling for mutual recursion.
 	// Pushing now is the cheap half: it keeps lambdas correct when
-	// a named fn is declared inside them.
-	tc.pushReturnFrame()
+	// a named fn is declared inside them. We feed the declared
+	// return (if any) so body returns get checked against it at
+	// their own span, same as lambdas.
+	var declaredReturn rl.TypingT
+	if n.Typing != nil && n.Typing.ReturnT != nil {
+		declaredReturn = *n.Typing.ReturnT
+	}
+	tc.pushReturnFrame(declaredReturn)
 	tc.walkStmts(n.Body)
 	_ = tc.popReturnFrame()
 	tc.frame = saved
@@ -2172,20 +2199,32 @@ func (tc *typeChecker) synthLambda(n *rl.Lambda) rl.TypingT {
 	// frame'\''s narrowings - that'\''s closure semantics. The
 	// reassignment-after-definition lookahead that would invalidate
 	// stale narrowings is still deferred (see docstring).
-	tc.pushReturnFrame()
+	//
+	// Feed the declared return (if any) into the return frame so
+	// each `return E` in the body gets checked against the
+	// declaration at its own span. Lambdas without a declared
+	// return have nothing to check against; the inferred return
+	// flows out via popReturnFrame.
+	var declaredReturn rl.TypingT
+	if n.Typing != nil && n.Typing.ReturnT != nil {
+		declaredReturn = *n.Typing.ReturnT
+	}
+	tc.pushReturnFrame(declaredReturn)
 
 	// Expression-form lambdas (`fn(x) x + 1`) put the expression
 	// node directly in Body (verified against the converter output -
 	// it does not wrap in ExprStmt). Each body entry is the value to
-	// return; synth it to feed the inferred return type. Block-form
-	// lambdas walk via walkStmts and rely on the `*rl.Return` case
-	// in walkStmt to populate returnStack.
+	// return; synth it to feed the inferred return type. We pass
+	// the body node itself as the diagnostic span - it'\''s the
+	// implicit return for these. Block-form lambdas walk via
+	// walkStmts and rely on the `*rl.Return` case to populate
+	// returnStack.
 	if !n.IsBlock {
 		for _, stmt := range n.Body {
 			if stmt == nil {
 				continue
 			}
-			tc.recordReturn(tc.synth(stmt))
+			tc.recordReturn(tc.synth(stmt), stmt)
 		}
 	} else {
 		tc.walkStmts(n.Body)