feat(typing): introduce TypingNullT for sound null literal handling

Before this change, the `null` literal synthesized to Dynamic, which
made `a: int = null` (and every other typed-slot-with-null) silently
type-check. Reassignments to null left the narrowed type as Dynamic
too, so subsequent reads didn't reflect "this is definitely null."
Inferred returns mixing a value and null produced int|dynamic instead
of int?.

New leaf type TypingNullT:
- LitNull synth uses TypingNullT instead of Dynamic.
- TypingNullT only flows into slots that admit null - Optional<T>,
  unions containing null, any/dynamic. Non-nullable slots emit
  RAD30001 (the existing nullable-suggestion diagnostic). User-
  facing name is "null"; users never write it as a standalone
  annotation (T? remains the canonical spelling).
- TypingOptionalT.IsAssignableFrom learns to accept TypingNullT
  directly (in addition to T and Optional<T>).

Narrowing now has a definite answer on the null side:
- narrowNullEquality returns TypingNullT on the "x == null" arm,
  replacing the previous no-op. Downstream type_of("null") dispatch
  and "subtract the non-null arm" patterns see x as definitely null.
- narrowByTypeOf for Optional<T> returns TypingNullT on the null
  arm (truthy when target == "null", falsy when target matched the
  non-null inner type).
- joinNarrowArms and unionTypesForJoin both collapse `T | null` to
  `T?` so two-arm narrowing results match how users spell nullable
  themselves (e.g. type_of-narrowing `int?|str` produces `str?` on
  the non-int branch instead of `null|str`).

The existing matchesTypeOf("null") returned false unconditionally;
now it returns true for TypingNullT leaves so the new narrowing
arms compose with downstream type_of guards.

Snapshots in narrow/null.snap: a: int = null fires, a: int? = null
clean, else-of-!=null narrows to TypingNullT, and a fn mixing
return 5 / return null synthesizes to int?. Drift in
narrow/nested_fn.snap (x reassigned to null now types null, not
dynamic) and narrow/type_of.snap (b in the else branch collapses
to str?) is the expected canonicalisation.

Author: amterp

rts/check/narrow.go

@@ -232,14 +232,10 @@ func mergeRefinementMaps(a, b map[*Symbol]rl.TypingT) map[*Symbol]rl.TypingT {
 // narrowNullEquality is invoked after the dispatcher confirms the
 // shape is `<ident> ==/!= null` (in either operand order). It looks
 // up the symbol, peels the nullable component from the base type, and
-// records the non-null type on the appropriate branch.
-//
-// The "narrow x to null" side is intentionally a no-op. We have no
-// TypingNullT in the static system, and the practical payoff of "x is
-// null in this branch" is small (users rarely access members of a
-// definitely-null value). Adding TypingNullT later is a pure expansion:
-// existing scripts keep working, the null branch just gains a tighter
-// static answer.
+// records both the non-null branch and the definitely-null branch.
+// With TypingNullT in the system, the previously-no-op null side now
+// narrows to TypingNullT - downstream `type_of(x) == "null"` dispatch
+// and similar patterns see x as definitely null in the matching arm.
 func (tc *typeChecker) narrowNullEquality(op rl.Operator, ident *rl.Identifier, frame *Frame) Refinement {
 	sym, ok := tc.resolved.Uses[ident]
 	if !ok || sym == nil {
@@ -254,11 +250,12 @@ func (tc *typeChecker) narrowNullEquality(op rl.Operator, ident *rl.Identifier,
 		return EmptyRefinement()
 	}
 	nonNullBranch := map[*Symbol]rl.TypingT{sym: nonNull}
+	nullBranch := map[*Symbol]rl.TypingT{sym: rl.NewNullType()}
 	switch op {
 	case rl.OpEq:
-		return Refinement{WhenTrue: map[*Symbol]rl.TypingT{}, WhenFalse: nonNullBranch}
+		return Refinement{WhenTrue: nullBranch, WhenFalse: nonNullBranch}
 	case rl.OpNeq:
-		return Refinement{WhenTrue: nonNullBranch, WhenFalse: map[*Symbol]rl.TypingT{}}
+		return Refinement{WhenTrue: nonNullBranch, WhenFalse: nullBranch}
 	}
 	return EmptyRefinement()
 }
@@ -593,12 +590,8 @@ func matchesTypeOf(t rl.TypingT, target string) bool {
 		_, ok := t.(*rl.TypingFnT)
 		return ok
 	case "null":
-		// No TypingNullT today; the null component is implicit in
-		// TypingOptionalT and not directly representable as a leaf.
-		// narrowByTypeOf handles the optional case explicitly so this
-		// branch is only hit for non-nullable leaves, where the answer
-		// is unambiguously false.
-		return false
+		_, ok := t.(*rl.TypingNullT)
+		return ok
 	}
 	return false
 }
@@ -619,32 +612,22 @@ func matchesTypeOf(t rl.TypingT, target string) bool {
 //     this arm means we keep the whole arm as a fallback.
 //   - Optional<T>:
 //       target == "null":
-//         truthy: x is null. We have no TypingNullT, so we return
-//                 the original Optional<T> as the conservative
-//                 over-approximation - the value is still typed as
-//                 nullable, and the union-walk caller can rely on
-//                 the arm not being silently dropped.
+//         truthy: TypingNullT (definite - the null arm matched).
 //         falsy:  x is non-null - return T.
 //       inner matches target:
 //         truthy: T (the non-null component).
-//         falsy:  x is null - return Optional<T> conservatively
-//                 (no TypingNullT). This preserves the null arm
-//                 when the optional sits inside a union and the
-//                 other arms don'\''t fold it back in.
+//         falsy:  TypingNullT (only possibility left).
 //       inner doesn'\''t match target:
 //         truthy: Never (inner doesn'\''t match, null doesn'\''t
 //                 match any non-null target).
 //         falsy:  the original Optional<T> stays.
-//   - Leaf (non-Optional):
+//   - TypingNullT (definite-null leaf):
+//       target == "null":  truthy=null, falsy=Never.
+//       any other target:  truthy=Never, falsy=null.
+//   - Leaf (non-Optional, non-null):
 //       target == "null": truthy=Never, falsy=base.
 //       matches:           truthy=base,  falsy=Never.
-//       doesn'\''t match:    truthy=Never, falsy=base.
-//
-// The shift from the previous behavior: Optional cases now return
-// the original Optional<T> rather than nil on the side that has
-// "the null half is still possible." This stops union arm walks
-// from silently dropping the null arm when a non-null target
-// matched a different union arm.
+//       doesn'\''t match:   truthy=Never, falsy=base.
 func narrowByTypeOf(base rl.TypingT, target string) (truthy, falsy rl.TypingT) {
 	if base == nil {
 		return nil, nil
@@ -677,22 +660,25 @@ func narrowByTypeOf(base rl.TypingT, target string) (truthy, falsy rl.TypingT) {
 	if o, ok := base.(*rl.TypingOptionalT); ok {
 		inner := o.Inner()
 		if target == "null" {
-			// Truthy: x IS null. No TypingNullT, so keep the optional
-			// as the conservative "value is still nullable" answer.
+			// Truthy: x IS null - return TypingNullT (definite).
 			// Falsy: x is non-null = the inner type.
-			return base, inner
+			return rl.NewNullType(), inner
 		}
 		if matchesTypeOf(inner, target) {
 			// Truthy: non-null inner matched. Falsy: only possibility
-			// left is null - keep Optional<T> as the conservative
-			// "still nullable" answer; this preserves the null arm
-			// when used inside a union walk.
-			return inner, base
+			// left is null.
+			return inner, rl.NewNullType()
 		}
 		// Inner doesn'\''t match target and null doesn'\''t match any
 		// non-null target. Truthy is empty; falsy is the original.
 		return rl.NewNeverType(), base
 	}
+	if _, ok := base.(*rl.TypingNullT); ok {
+		if target == "null" {
+			return base, rl.NewNeverType()
+		}
+		return rl.NewNeverType(), base
+	}
 	if target == "null" {
 		return rl.NewNeverType(), base
 	}
@@ -712,13 +698,26 @@ func isNeverType(t rl.TypingT) bool {
 
 // joinNarrowArms collapses a slice of narrowed arms into a single
 // TypingT: empty -> Never (no remaining arms means the branch is
-// unreachable), one arm -> that arm, more -> a union.
+// unreachable), one arm -> that arm, more -> a union. Two-arm unions
+// with a null component collapse to T? to match how users spell
+// nullable types and how unionTypesForJoin canonicalises inferred
+// returns.
 func joinNarrowArms(arms []rl.TypingT) rl.TypingT {
 	switch len(arms) {
 	case 0:
 		return rl.NewNeverType()
 	case 1:
 		return arms[0]
+	case 2:
+		if _, leftNull := arms[0].(*rl.TypingNullT); leftNull {
+			if _, rightNull := arms[1].(*rl.TypingNullT); !rightNull {
+				return rl.NewOptionalType(arms[1])
+			}
+		}
+		if _, rightNull := arms[1].(*rl.TypingNullT); rightNull {
+			return rl.NewOptionalType(arms[0])
+		}
+		return rl.NewUnionType(arms...)
 	default:
 		return rl.NewUnionType(arms...)
 	}

rts/check/narrow_interp_test.go

@@ -64,27 +64,32 @@ func makeChecker(baseType rl.TypingT) (*typeChecker, *rl.Identifier, *Symbol) {
 
 func TestInterpretCondition_NeqNullNarrowsTruthyToNonNull(t *testing.T) {
 	// `x != null` where x: int?
-	// Truthy branch should narrow x to int.
+	// Truthy branch narrows x to int; falsy branch narrows x to null.
 	tc, ident, sym := makeChecker(rl.NewOptionalType(rl.NewIntType()))
 	cond := rl.NewOpBinary(rl.Span{}, rl.OpNeq, ident, rl.NewLitNull(rl.Span{}))
 	r := tc.interpretCondition(cond, nil)
 
 	got, ok := r.WhenTrue[sym]
-	require.True(t, ok, "truthy branch should narrow x")
+	require.True(t, ok, "truthy branch should narrow x to non-null")
 	assert.Equal(t, rl.T_INT, got.Name())
-	assert.Empty(t, r.WhenFalse, "falsy branch should record no narrowing (null side)")
+	nullGot, ok := r.WhenFalse[sym]
+	require.True(t, ok, "falsy branch should narrow x to null")
+	assert.Equal(t, "null", nullGot.Name())
 }
 
 func TestInterpretCondition_EqNullNarrowsFalsyToNonNull(t *testing.T) {
-	// `x == null` where x: str? - inverse of the != case.
+	// `x == null` where x: str?
+	// Truthy narrows x to null; falsy narrows x to str.
 	tc, ident, sym := makeChecker(rl.NewOptionalType(rl.NewStrType()))
 	cond := rl.NewOpBinary(rl.Span{}, rl.OpEq, ident, rl.NewLitNull(rl.Span{}))
 	r := tc.interpretCondition(cond, nil)
 
 	got, ok := r.WhenFalse[sym]
 	require.True(t, ok, "falsy branch should narrow x to non-null")
 	assert.Equal(t, rl.T_STR, got.Name())
-	assert.Empty(t, r.WhenTrue, "truthy branch (null side) should record no narrowing")
+	nullGot, ok := r.WhenTrue[sym]
+	require.True(t, ok, "truthy branch should narrow x to null")
+	assert.Equal(t, "null", nullGot.Name())
 }
 
 func TestInterpretCondition_SwappedOperandsStillNarrows(t *testing.T) {
@@ -158,25 +163,24 @@ func TestNarrowByTypeOf_LeafNoMatch(t *testing.T) {
 }
 
 func TestNarrowByTypeOf_OptionalInnerMatches(t *testing.T) {
-	// Optional<int>, target="int" => truthy: int, falsy: int? (the
-	// conservative "value is still nullable" approximation since we
-	// have no TypingNullT to represent "definitely null").
+	// Optional<int>, target="int" => truthy: int, falsy: null
+	// (TypingNullT - definite, the only remaining possibility).
 	base := rl.NewOptionalType(rl.NewIntType())
 	truthy, falsy := narrowByTypeOf(base, "int")
 	require.NotNil(t, truthy)
 	assert.Equal(t, rl.T_INT, truthy.Name())
-	require.NotNil(t, falsy, "null half stays as Optional, not nil")
-	assert.Equal(t, "int?", falsy.Name(),
-		"falsy keeps the optional - the only remaining possibility is null")
+	require.NotNil(t, falsy)
+	assert.Equal(t, "null", falsy.Name(),
+		"falsy is definite null after the inner-int branch is taken")
 }
 
 func TestNarrowByTypeOf_OptionalNullTarget(t *testing.T) {
-	// Optional<int>, target="null" => truthy: int? (no TypingNullT,
-	// keep the optional), falsy: int.
+	// Optional<int>, target="null" => truthy: null (definite),
+	// falsy: int.
 	base := rl.NewOptionalType(rl.NewIntType())
 	truthy, falsy := narrowByTypeOf(base, "null")
-	require.NotNil(t, truthy, "truthy keeps the optional - null half")
-	assert.Equal(t, "int?", truthy.Name())
+	require.NotNil(t, truthy, "truthy is the definite-null arm")
+	assert.Equal(t, "null", truthy.Name())
 	require.NotNil(t, falsy)
 	assert.Equal(t, rl.T_INT, falsy.Name())
 }

rts/check/snapshots/narrow/nested_fn.snap

@@ -42,17 +42,17 @@ fn f(x: int?):
   x @ 2:8 -> int?
   x @ 4:13 -> <no-type>
   y @ 5:13 -> <no-type>
-  x @ 5:17 -> dynamic
+  x @ 5:17 -> null
   after_inner @ 6:9 -> <no-type>
   x @ 6:23 -> int
 
 # Symbol types
   after_inner (local): int
   f (fn): fn(int?) -> void
   g (fn): fn() -> void
-  x (local): dynamic
+  x (local): null
   x (param): int?
-  y (local): dynamic
+  y (local): null
 
 # Diagnostics
   (none)

rts/check/snapshots/narrow/null.snap

@@ -74,3 +74,85 @@ fn f(x: int):
 
 # Diagnostics
   (none)
+### TITLE ###
+NullLiteralRejectedByNonNullableSlot
+### DESCRIPTION ###
+The null literal synthesizes to TypingNullT, which is only
+assignable to slots that admit null. A bare `a: int = null`
+fires a type-mismatch diagnostic.
+### INPUT ###
+a: int = null
+### STDOUT ###
+# Identifier types
+  a @ 1:1 -> <no-type>
+
+# Symbol types
+  a (local): int
+
+# Diagnostics
+  [hint] RAD30001 @ 1:10 - Value of type 'null' is not assignable to declared type 'int'
+### TITLE ###
+NullLiteralAcceptedByOptionalSlot
+### DESCRIPTION ###
+TypingNullT flows freely into T? slots.
+### INPUT ###
+a: int? = null
+### STDOUT ###
+# Identifier types
+  a @ 1:1 -> <no-type>
+
+# Symbol types
+  a (local): int?
+
+# Diagnostics
+  (none)
+### TITLE ###
+NotNullElseNarrowsToNull
+### DESCRIPTION ###
+The else branch of `if x != null:` narrows x to TypingNullT
+(definite null). Regression lock against the previous no-op,
+which left x typed as the un-narrowed `int?`.
+### INPUT ###
+fn f(x: int?):
+    if x != null:
+        a = x
+    else:
+        b = x
+### STDOUT ###
+# Identifier types
+  x @ 2:8 -> int?
+  a @ 3:9 -> <no-type>
+  x @ 3:13 -> int
+  b @ 5:9 -> <no-type>
+  x @ 5:13 -> null
+
+# Symbol types
+  a (local): int
+  b (local): null
+  f (fn): fn(int?) -> void
+  x (param): int?
+
+# Diagnostics
+  (none)
+### TITLE ###
+InferredReturnMixingValueAndNullProducesOptional
+### DESCRIPTION ###
+A fn that returns 5 in one branch and null in another should
+synthesize to `int?`, the canonical nullable form. Previously
+this produced `int|dynamic` because null synth fell back to
+Dynamic.
+### INPUT ###
+fn maybe(b: bool):
+    if b:
+        return 5
+    return null
+### STDOUT ###
+# Identifier types
+  b @ 2:8 -> bool
+
+# Symbol types
+  b (param): bool
+  maybe (fn): fn(bool) -> int?
+
+# Diagnostics
+  (none)

rts/check/snapshots/narrow/type_of.snap

@@ -45,11 +45,11 @@ fn f(x: int?|str):
   a @ 3:9 -> <no-type>
   x @ 3:13 -> int
   b @ 5:9 -> <no-type>
-  x @ 5:13 -> int?|str
+  x @ 5:13 -> str?
 
 # Symbol types
   a (local): int
-  b (local): int?|str
+  b (local): str?
   f (fn): fn(int?|str) -> void
   x (param): int?|str
 

rts/check/type_check.go

@@ -1558,6 +1558,21 @@ func unionTypesForJoin(types []rl.TypingT) rl.TypingT {
 		return rl.NewNeverType()
 	case 1:
 		return flat[0]
+	case 2:
+		// `T | null` is the canonical nullable shape - collapse it to
+		// `T?` (TypingOptionalT) so inferred returns and narrowing
+		// joins read the way users spell nullable themselves. Multi-
+		// arm unions with null (e.g. `int|str|null`) stay as a union
+		// since `T|U?` is ambiguous to read.
+		if _, leftNull := flat[0].(*rl.TypingNullT); leftNull {
+			if _, rightNull := flat[1].(*rl.TypingNullT); !rightNull {
+				return rl.NewOptionalType(flat[1])
+			}
+		}
+		if _, rightNull := flat[1].(*rl.TypingNullT); rightNull {
+			return rl.NewOptionalType(flat[0])
+		}
+		return rl.NewUnionType(flat...)
 	default:
 		return rl.NewUnionType(flat...)
 	}
@@ -2036,11 +2051,12 @@ func (tc *typeChecker) synth(n rl.Node) rl.TypingT {
 	case *rl.LitBool:
 		return tc.record(v, rl.NewBoolType())
 	case *rl.LitNull:
-		// Rad models nullability via Optional<T>; a bare null literal
-		// without context is best-typed as Dynamic until later
-		// sub-commits give us a way to bubble the expected type into
-		// synth (the "check" direction of bidirectional checking).
-		return tc.record(v, rl.NewDynamicType())
+		// Rad's `null` literal has a dedicated static type so it
+		// only flows into slots that admit null (Optional<T>, unions
+		// containing null, any/dynamic). Synthesizing Dynamic here
+		// would silently fit any typed slot - a soundness gap that
+		// let `a: int = null` slip through.
+		return tc.record(v, rl.NewNullType())
 	case *rl.Identifier:
 		return tc.synthIdentifier(v)
 	case *rl.Call: