feat(check): typed local declarations end-to-end

Pair with the tree-sitter-rad grammar change introducing the
typed_assign rule and the BLOCK_COLON external token. This commit
handles the rad-side wiring: converter -> AST -> binder -> type
checker -> tests, plus snapshot updates from the CST shape change.

The converter desugars typed_assign into the existing Assign AST
node with a new optional DeclaredType field. Keeping a single
Assign kind downstream means every existing pass (walkAST, binder
visit dispatch, interpreter exec) stays unchanged; the only new
concept is 'this Assign carries an annotation.' One AST shape,
two source forms.

Symbol gains a Declared slot. The binder reads it from
Assign.DeclaredType the moment a typed local is declared, and the
type checker enforces the annotation on both the initial RHS AND
every subsequent reassignment - the annotation is sticky for the
binding's lifetime. Untyped locals stay completely unchanged: no
Declared, no reassignment constraint, no diagnostic.

The grammar's external-scanner trick (BLOCK_COLON only emitted
when ':' is followed by a newline) means variables named exactly
`rad` / `request` / `display` ALSO carry annotations
unambiguously - `rad: int = 5` parses as a typed_assign, not a
rad_block. A dedicated test pins that down so any future grammar
regression on the scanner peek surfaces immediately.

Severity stays at Hint, consistent with the rest of Phase 2's
assignability checks (per-arg type-check, op overload). The
runtime still produces its richer value-aware message when it
runs; the static check just surfaces the issue earlier in LSP and
rad check. One severity-migration pass will flip every
assignability check together once literal-type fidelity exists.

The ST snapshot updates are mechanical: rad_block's CST no longer
contains a visible `:` literal child (BLOCK_COLON is a hidden
external token) so the dump lines for that node disappear.
AST shapes are unchanged.

Author: amterp

rts/check/binder.go

@@ -272,6 +272,17 @@ func (b *binder) visitAssign(a *rl.Assign) {
 	for _, target := range a.Targets {
 		b.declareTarget(target, a.UpdateEnclosing)
 	}
+	// Typed local: `x: int = 5`. The converter only attaches
+	// DeclaredType on single-target assigns today, so we plant the
+	// annotation on the first target's symbol if it's a fresh local
+	// the binder just declared.
+	if a.DeclaredType != nil && len(a.Targets) > 0 {
+		if ident, ok := a.Targets[0].(*rl.Identifier); ok {
+			if sym, ok := b.resolved.Uses[ident]; ok && sym != nil {
+				sym.Declared = *a.DeclaredType
+			}
+		}
+	}
 	if a.Catch != nil {
 		b.visitCatch(a.Catch)
 	}

rts/check/resolve.go

@@ -68,6 +68,12 @@ type Symbol struct {
 	DeclSpan rl.Span // location of the declaration in source; zero for builtins
 	DefNode  rl.Node // the AST node that declared the symbol; nil for builtins
 	Scope    *Scope  // scope this symbol lives in; the builtin scope for SymBuiltin
+	// Declared is the user-written type annotation pinned to this
+	// binding (e.g. the `int` in `x: int = 5`). Once set it never
+	// changes; subsequent reassignments must remain assignable to it.
+	// nil for unannotated locals - those carry only an Inferred type
+	// that the type checker derives from the RHS.
+	Declared rl.TypingT
 }
 
 // Scope is a lexical name -> Symbol table chained to its parent. Lookup

rts/check/type_check.go

@@ -121,6 +121,13 @@ func (tc *typeChecker) walkCmd(c *rl.CmdBlock) {
 // type of the LHS symbol. Multi-value RHS aligns 1:1 with multi-
 // target LHS at this stage; unpacking (where one RHS expression
 // produces multiple values) is deferred.
+//
+// For typed locals (`x: int = 5`, with sym.Declared set) the RHS
+// must be assignable to the declared type, and the recorded symbol
+// type stays Declared rather than the RHS-derived value. Subsequent
+// `x = something` reassignments are checked against the same
+// Declared, so the annotation acts as a stable contract for every
+// later read of the binding.
 func (tc *typeChecker) walkAssign(a *rl.Assign) {
 	for i, val := range a.Values {
 		valType := tc.synth(val)
@@ -135,10 +142,41 @@ func (tc *typeChecker) walkAssign(a *rl.Assign) {
 		if !ok {
 			continue
 		}
+		if sym.Declared != nil {
+			tc.checkAssignAgainstDeclared(val, valType, sym.Declared)
+			tc.info.SymbolTypes[sym] = sym.Declared
+			continue
+		}
 		tc.info.SymbolTypes[sym] = valType
 	}
 }
 
+// checkAssignAgainstDeclared emits a type-mismatch when the assigned
+// value can't flow into the declared slot. Severity matches Phase 2's
+// per-arg precedent: Hint, not Error - the runtime still produces a
+// richer value-aware message when the script runs, and we only
+// promote once literal types fill the missing fidelity (a one-pass
+// severity migration covers all assignability checks at once).
+//
+// ErrorType / Dynamic short-circuit: a poisoned RHS already produced
+// a diagnostic and any-likes are universally assignable, so no extra
+// diagnostic fires.
+func (tc *typeChecker) checkAssignAgainstDeclared(valNode rl.Node, valType, declared rl.TypingT) {
+	if valType == nil || isErrorType(valType) || isDynamicLike(valType) {
+		return
+	}
+	if declared.IsAssignableFrom(valType) {
+		return
+	}
+	tc.info.Issues = append(tc.info.Issues, BindIssue{
+		Span:     valNode.Span(),
+		Severity: IssueHint,
+		Code:     rl.ErrTypeMismatch,
+		Message: fmt.Sprintf("Value of type '%s' is not assignable to declared type '%s'",
+			valType.Name(), declared.Name()),
+	})
+}
+
 // synth returns the static type of an expression node and records it
 // on the ExprTypes index.
 //

rts/check/type_check_test.go

@@ -668,3 +668,112 @@ func TestTypeCheck_IntPlusListDoesNotAttachStrMigrationHint(t *testing.T) {
 		}
 	}
 }
+
+// --- Typed local declaration tests (Phase 3) -------------------------
+
+func TestTypeCheck_TypedLocalRecordsDeclaredType(t *testing.T) {
+	// `x: int = 5` - the symbol's recorded type should be the
+	// declared `int`, not the RHS's synth result (which happens to
+	// also be int here, but the point is the binder set Declared and
+	// the checker used it).
+	file, info, resolved := typeInfoFromSrc(t, "x: int = 5\n")
+	target := file.Stmts[0].(*rl.Assign).Targets[0].(*rl.Identifier)
+	sym := resolved.Uses[target]
+	require.NotNil(t, sym)
+	require.NotNil(t, sym.Declared, "binder should populate Declared")
+	assert.Equal(t, rl.T_INT, sym.Declared.Name())
+	assert.Equal(t, rl.T_INT, info.SymbolTypes[sym].Name())
+}
+
+func TestTypeCheck_TypedLocalAcceptsAssignableRHS(t *testing.T) {
+	// int literal flows into `: int` slot without diagnostic.
+	_, info, _ := typeInfoFromSrc(t, "x: int = 5\n")
+	for _, i := range info.Issues {
+		assert.NotEqual(t, rl.ErrTypeMismatch, i.Code,
+			"valid typed local should not produce a type-mismatch")
+	}
+}
+
+func TestTypeCheck_TypedLocalRejectsIncompatibleRHS(t *testing.T) {
+	// str literal can't flow into `: int`. Hint severity matches the
+	// rest of Phase 2's assignability precedent.
+	_, info, _ := typeInfoFromSrc(t, "x: int = \"hi\"\n")
+	found := false
+	for _, i := range info.Issues {
+		if i.Code == rl.ErrTypeMismatch && i.Severity == check.IssueHint {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found,
+		"expected a Hint-severity type-mismatch when RHS isn't assignable to declared")
+}
+
+func TestTypeCheck_TypedLocalDeclaredFloatAcceptsInt(t *testing.T) {
+	// The single implicit widening: int flows into float. So
+	// `x: float = 5` is fine, no diagnostic.
+	_, info, _ := typeInfoFromSrc(t, "x: float = 5\n")
+	for _, i := range info.Issues {
+		assert.NotEqual(t, rl.ErrTypeMismatch, i.Code)
+	}
+}
+
+func TestTypeCheck_TypedLocalReassignChecksAgainstDeclared(t *testing.T) {
+	// After `x: int = 5`, a later `x = "hi"` should still be flagged
+	// against the original declared type. The annotation is sticky
+	// for the binding's lifetime.
+	_, info, _ := typeInfoFromSrc(t, "x: int = 5\nx = \"hi\"\n")
+	count := 0
+	for _, i := range info.Issues {
+		if i.Code == rl.ErrTypeMismatch {
+			count++
+		}
+	}
+	assert.Equal(t, 1, count,
+		"reassignment with incompatible type should fire one type-mismatch")
+}
+
+func TestTypeCheck_TypedLocalDeclaredAnyAcceptsAnything(t *testing.T) {
+	// `: any` is the user-opt-in escape hatch - every type flows in.
+	_, info, _ := typeInfoFromSrc(t, "x: any = 5\nx = \"hi\"\n")
+	for _, i := range info.Issues {
+		assert.NotEqual(t, rl.ErrTypeMismatch, i.Code,
+			"any-typed local should accept any RHS")
+	}
+}
+
+func TestTypeCheck_UntypedLocalUnchanged(t *testing.T) {
+	// Sanity check that the introduction of typed locals doesn't
+	// disturb the existing untyped path. `x = 5; x = "hi"` should
+	// still rebind freely (no declared annotation means no
+	// reassignment constraint).
+	_, info, _ := typeInfoFromSrc(t, "x = 5\nx = \"hi\"\n")
+	for _, i := range info.Issues {
+		assert.NotEqual(t, rl.ErrTypeMismatch, i.Code,
+			"untyped local should accept any reassignment")
+	}
+}
+
+func TestTypeCheck_TypedLocalWithRadBlockKeywordName(t *testing.T) {
+	// Variables named `rad` / `request` / `display` (the rad_block
+	// keywords) can ALSO be typed-locals. The external scanner's
+	// BLOCK_COLON peek distinguishes a typed-assign's ':' from a
+	// rad_block's block-colon by what follows it, so `rad: int = 5`
+	// is unambiguously a typed-local declaration regardless of the
+	// keyword overlap. This test pins that down.
+	file, info, resolved := typeInfoFromSrc(t, "rad: int = 5\n")
+	require.NotEmpty(t, file.Stmts, "should produce one stmt")
+	assign, ok := file.Stmts[0].(*rl.Assign)
+	require.True(t, ok, "expected Assign, got %T", file.Stmts[0])
+	require.NotNil(t, assign.DeclaredType,
+		"typed_assign with `rad` LHS should carry DeclaredType")
+	ident := assign.Targets[0].(*rl.Identifier)
+	assert.Equal(t, "rad", ident.Name)
+	sym := resolved.Uses[ident]
+	require.NotNil(t, sym)
+	assert.Equal(t, rl.T_INT, sym.Declared.Name())
+	for _, i := range info.Issues {
+		assert.NotEqual(t, rl.ErrTypeMismatch, i.Code,
+			"int RHS into `rad: int` should not produce a mismatch")
+	}
+}

rts/converter.go

@@ -81,6 +81,8 @@ func (c *converter) convertStmt(node *ts.Node) rl.Node {
 	switch node.Kind() {
 	case rl.K_ASSIGN:
 		return c.convertAssign(node)
+	case rl.K_TYPED_ASSIGN:
+		return c.convertTypedAssign(node)
 	case rl.K_COMPOUND_ASSIGN:
 		return c.convertCompoundAssign(node)
 	case rl.K_INCR_DECR:
@@ -146,6 +148,32 @@ func (c *converter) convertAssign(node *ts.Node) *rl.Assign {
 	return rl.NewAssign(c.makeSpan(node), targets, values, true, catch)
 }
 
+// convertTypedAssign desugars `x: int = 5` into the same Assign AST
+// node the rest of the pipeline already understands, with the
+// declared type attached. Keeping the shape uniform means every
+// downstream pass (walkers, binder, checker, interpreter) sees one
+// Assign kind whether the user wrote a type or not.
+func (c *converter) convertTypedAssign(node *ts.Node) *rl.Assign {
+	catchNode := rl.GetChild(node, rl.F_CATCH)
+	var catch *rl.CatchBlock
+	if catchNode != nil {
+		catch = c.convertCatchBlock(catchNode)
+	}
+
+	leftNode := rl.GetChild(node, rl.F_LEFT)
+	rightNode := rl.GetChild(node, rl.F_RIGHT)
+	target := c.convertExpr(leftNode)
+	value := c.convertExpr(rightNode)
+
+	assign := rl.NewAssign(c.makeSpan(node), []rl.Node{target}, []rl.Node{value}, false, catch)
+
+	if typeNode := rl.GetChild(node, rl.F_DECLARED_TYPE); typeNode != nil {
+		declaredType := rl.ResolveTyping(typeNode, c.src)
+		assign.DeclaredType = &declaredType
+	}
+	return assign
+}
+
 // convertCompoundAssign desugars `x += 3` into `Assign(x, OpBinary(x, +, 3))`.
 func (c *converter) convertCompoundAssign(node *ts.Node) *rl.Assign {
 	leftNode := rl.GetChild(node, rl.F_LEFT)

rts/rl/ast_types.go

@@ -26,6 +26,13 @@ type Assign struct {
 	IsUnpacking     bool        // true if `a, b = ...` syntax
 	UpdateEnclosing bool        // true for compound assign/incr-decr (updates enclosing scope)
 	Catch           *CatchBlock // optional catch block
+	// DeclaredType is the optional `: type` annotation on the LHS of
+	// typed local declarations (`x: int = 5`). Today only the
+	// single-target form carries one; nil for every other shape and
+	// for plain untyped assigns. The binder reads this onto the
+	// declared Symbol so the type checker can enforce the RHS
+	// against it.
+	DeclaredType *TypingT
 }
 
 func NewAssign(span Span, targets, values []Node, isUnpacking bool, catch *CatchBlock) *Assign {

rts/rl/consts.go

@@ -51,6 +51,7 @@ const (
 	K_MAP                      = "map"
 	K_IDENTIFIER               = "identifier"
 	K_COMPOUND_ASSIGN          = "compound_assign"
+	K_TYPED_ASSIGN             = "typed_assign"
 	K_PLUS_EQUAL               = "+="
 	K_MINUS_EQUAL              = "-="
 	K_STAR_EQUAL               = "*="
@@ -169,6 +170,7 @@ const (
 	F_CATCH               = "catch"
 	F_TYPE                = "type"
 	F_RETURN_TYPE         = "return_type"
+	F_DECLARED_TYPE       = "declared_type"
 	F_VARARG_MARKER       = "vararg_marker"
 	F_VARIADIC_MARKER     = "variadic_marker" // todo merge with above
 	F_OPTIONAL            = "optional"

rts/rl/typing_resolution.go

@@ -66,6 +66,14 @@ func resolveParams(resolvedParams *[]TypingFnParam, src string, paramNodes []ts.
 	}
 }
 
+// ResolveTyping is the public entry point to resolveTyping for callers
+// outside the rl package (e.g. the converter wiring typed locals).
+// Accepts a CST node of kind fn_param_or_return_type and returns the
+// corresponding static TypingT.
+func ResolveTyping(node *ts.Node, src string) TypingT {
+	return resolveTyping(node, src)
+}
+
 // input node expected to be kind 'fn_param_or_return_type'
 func resolveTyping(node *ts.Node, src string) TypingT {
 	leafNodes := GetChildren(node, F_LEAF_TYPE)

rts/test/st_snapshots/complete.snap

@@ -744,7 +744,6 @@ B: [ 477,  480] PS: [ 37,  4] PE: [ 37,  7]                     delegate: fallba
 B: [ 477,  480] PS: [ 37,  4] PE: [ 37,  7]                       delegate: catch_expr
 B: [ 477,  480] PS: [ 37,  4] PE: [ 37,  7]                         delegate: var_path
 B: [ 477,  480] PS: [ 37,  4] PE: [ 37,  7]                           root: identifier `url`
-B: [ 480,  481] PS: [ 37,  7] PE: [ 37,  8]     : `:`
 B: [ 486,  499] PS: [ 38,  4] PE: [ 38, 17]     stmt: rad_field_stmt
 B: [ 486,  492] PS: [ 38,  4] PE: [ 38, 10]       fields `fields`
 B: [ 493,  495] PS: [ 38, 11] PE: [ 38, 13]       identifier: identifier `f1`
@@ -1019,7 +1018,6 @@ B: [ 755,  758] PS: [ 59,  4] PE: [ 59,  7]                     delegate: fallba
 B: [ 755,  758] PS: [ 59,  4] PE: [ 59,  7]                       delegate: catch_expr
 B: [ 755,  758] PS: [ 59,  4] PE: [ 59,  7]                         delegate: var_path
 B: [ 755,  758] PS: [ 59,  4] PE: [ 59,  7]                           root: identifier `url`
-B: [ 758,  759] PS: [ 59,  7] PE: [ 59,  8]     : `:`
 B: [ 764,  771] PS: [ 60,  4] PE: [ 60, 11]     stmt: rad_option_stmt
 B: [ 764,  771] PS: [ 60,  4] PE: [ 60, 11]       keyword: rad_option_keyword
 B: [ 764,  771] PS: [ 60,  4] PE: [ 60, 11]         noprint `noprint`
@@ -1029,7 +1027,6 @@ B: [ 783,  785] PS: [ 61, 11] PE: [ 61, 13]       identifier: identifier `f1`
 B: [ 787,  813] PS: [ 63,  0] PE: [ 64, 21]   rad_block
 B: [ 787,  790] PS: [ 63,  0] PE: [ 63,  3]     rad_type: rad_keyword
 B: [ 787,  790] PS: [ 63,  0] PE: [ 63,  3]       rad `rad`
-B: [ 790,  791] PS: [ 63,  3] PE: [ 63,  4]     : `:`
 B: [ 796,  813] PS: [ 64,  4] PE: [ 64, 21]     stmt: rad_field_stmt
 B: [ 796,  802] PS: [ 64,  4] PE: [ 64, 10]       fields `fields`
 B: [ 803,  805] PS: [ 64, 11] PE: [ 64, 13]       identifier: identifier `f2`

rts/test/st_snapshots/display_with_map.snap

@@ -41,7 +41,6 @@ B: [11, 12] PS: [1,  4] PE: [1,  5]                     delegate: fallback_expr
 B: [11, 12] PS: [1,  4] PE: [1,  5]                       delegate: catch_expr
 B: [11, 12] PS: [1,  4] PE: [1,  5]                         delegate: var_path
 B: [11, 12] PS: [1,  4] PE: [1,  5]                           root: identifier `a`
-B: [12, 13] PS: [1,  5] PE: [1,  6]     : `:`
 B: [18, 33] PS: [2,  4] PE: [2, 19]     stmt: rad_field_stmt
 B: [18, 24] PS: [2,  4] PE: [2, 10]       fields `fields`
 B: [25, 27] PS: [2, 11] PE: [2, 13]       identifier: identifier `ID`