feat(compiler): improve constraints, guards, and codegen

ROADMAP.md

@@ -70,13 +70,13 @@ The language surface is organized around **structural types**, **explicit annota
 
 | Feature | Status | Notes |
 | --- | --- | --- |
-| `ensure` statements (basic type assertions) | ✅ done | Validates assertions and optional blocks; does **not** narrow the subject’s type for statements **after** the `ensure` (see control-flow narrowing). |
+| `ensure` statements (basic type assertions) | ✅ done | Validates assertions and optional blocks. **Successor narrowing** after a successful `ensure` works for **simple identifiers** (`ensure x is …` then use `x` on the next lines); **compound paths** (e.g. `ensure req.state is …`) remain deferred (see control-flow narrowing). |
 | Shape guards (struct refinement) | ✅ done | Refinement on shapes. |
 | `is` operator for `ensure` conditions | ✅ done | Parser requires `ensure … is …` (see `forst/internal/parser/ensure.go`; `ensure !ident` uses implicit `Nil()`). The typechecker enforces presence (`Present`) and type-guard subject compatibility (`forst/internal/typechecker/unify_typeguard.go`, `infer_ensure.go`); it does **not** fully validate arbitrary built-in constraint semantics beyond that. Emission: `forst/internal/transformer/go/ensure.go`, `ensure_constraint.go`. Examples: `examples/in/ensure.ft` and `task example:ensure`. |
 | Type guards (beyond shape guards) | 🔬 experimental | Top-level `is (subject T) Name { … }` declarations are **implemented** end-to-end: parse (`forst/internal/parser/typeguard.go`), typecheck (`unify_typeguard.go`, registration in `Defs`), Go emit (`forst/internal/transformer/go/typeguard.go`, `ensure_typeguard.go`). Examples: `examples/in/rfc/guard/` (`task example:shape-guard`, `task example:basic-guard`). **Not** at full RFC “done” yet: narrowing across all control-flow positions and other polish overlap **Control-flow type narrowing**; language design: [type guards RFC](./examples/in/rfc/guard/guard.md); Go / `.d.ts` interop: [interop](./examples/in/rfc/guard/interop.md). |
 | Immutability guarantees (`ensure`-scoped; unsafe mode for Go interop) | 📋 planned | Not implemented. |
 | Binary type expressions (`A \| B`, `A & B`) | 🔬 experimental | Parser, AST, and typechecker support **`&`** / **`|`** on typedef bodies: unions flatten to **`TypeUnion`**, intersections use meet (`forst/internal/typechecker/typedef_binary.go`); Go emit lowers via canonical **`TypeNode`** (`forst/internal/transformer/go/typedef_expr.go`). **Closed unions of nominal errors** emit sealed Go interfaces (`error_union_sealed.go`); examples `union_error_types.ft`, `union_error_narrowing.ft`. **Gaps vs “done”:** general non-error unions, full intersection algebra, union narrowing in all control-flow positions, and TS/Go emit for arbitrary **`A \| B`** combinations—do not rely on binary typedef semantics beyond tested nominal-error and alias paths. **Narrowing** and future optionals should share one internal type algebra (assertions / `TypeNode`), not a parallel representation—see control-flow narrowing. |
-| Control-flow type narrowing | 🔬 experimental | **If-branch narrowing** for `if x is …` (assertion or shape RHS): refined type for the subject is recorded in the branch scope; variable types are keyed by identifier **and** source span in the typechecker so hover can differ per occurrence. Join/merge across branches and full `ensure`-successor narrowing are not done yet. Implementation: `forst/internal/typechecker/infer_if.go`, `narrow_if.go`; LSP uses `InferredTypesForVariableNode` when the variable AST node is found at the cursor. Type guards vs optionals / `Result`: [type guards & optionals](./examples/in/rfc/optionals/10-type-guards-shape-guards-and-optionals.md). |
+| Control-flow type narrowing | 🔬 experimental | **If-branch narrowing** for `if x is …` (assertion or shape RHS): refined type for the subject is recorded in the branch scope; variable types are keyed by identifier **and** source span in the typechecker so hover can differ per occurrence. **Ensure-successor narrowing** works for simple identifiers; compound paths and join/merge across branches are not done yet. Implementation: `forst/internal/typechecker/infer_if.go`, `narrow_if.go`; LSP uses `InferredTypesForVariableNode` when the variable AST node is found at the cursor. Type guards vs optionals / `Result`: [type guards & optionals](./examples/in/rfc/optionals/10-type-guards-shape-guards-and-optionals.md). |
 
 ### Generics, aliases, and nominal features
 

Taskfile.yml

@@ -223,6 +223,18 @@ tasks:
     cmds:
       - go run ./{{.BUILD_DIR}} run -loglevel trace -report-phases -- {{.EXAMPLES_DIR}}/union_error_types.ft
 
+  example:union-error-narrowing:
+    desc: Compile union error narrowing example (golden examples/out/union_error_narrowing.go)
+    dir: forst
+    cmds:
+      - go run ./{{.BUILD_DIR}} run -loglevel trace -report-phases -- {{.EXAMPLES_DIR}}/union_error_narrowing.ft
+
+  example:map-catalog:
+    desc: Compile map catalog example (golden examples/out/map_catalog.go)
+    dir: forst
+    cmds:
+      - go run ./{{.BUILD_DIR}} run -loglevel trace -report-phases -- {{.EXAMPLES_DIR}}/map_catalog.ft
+
   example:result-ensure:
     desc: Compile Result + ensure Ok() example (golden examples/out/result_ensure/)
     dir: forst

docs/language/shapes-and-constraints.mdx

@@ -8,7 +8,7 @@ import ShapesConstraintChaining from "/snippets/shapes-constraint-chaining.mdx";
 import ShapesPlaceOrderTags from "/snippets/shapes-place-order-tags.mdx";
 import ShapesAddressCustomer from "/snippets/shapes-address-customer.mdx";
 
-In Go you declare a struct and write manual checks. In Forst, **constraints live on the type**. The compiler emits runtime validation at the boundary.
+In Go you declare a struct and write manual checks. In Forst, **constraints live on the type**. Where values are known at compile time, the typechecker proves them statically; for dynamic input, use **`ensure … is …`** in the function body today. Automatic validation prologues on parameters are planned—not emitted yet.
 
 ## Manual validation in Go
 
@@ -35,7 +35,7 @@ The struct says nothing about valid ranges. Every handler repeats the same `if`
 
 <CatalogOrder />
 
-When `placeOrder` runs, the compiler has already proven the shape at compile time where values are known, and emits checks for dynamic input. Invalid SKUs and quantities never reach your catalog logic.
+When `placeOrder` runs, the compiler has already proven the shape at compile time where values are known; use `ensure` (or explicit checks) for dynamic input. Invalid SKUs and quantities never reach your catalog logic.
 
 ## Built-in constraints
 
@@ -95,7 +95,7 @@ Invalid nested data fails at the same boundary. You do not re-walk the tree in a
 
 ## What gets emitted
 
-The compiler lowers constraints to plain Go checks before your function body runs: `String.Min(1)` becomes a `len(field)` comparison, `Int.Min(1)` a numeric comparison, and `HasPrefix` / `Contains` call `strings.*` with an auto-added import. Generated Go stays readable and uses standard error returns. There is no hidden magic at runtime.
+The compiler lowers **`ensure`** checks in the function body to plain Go: `String.Min(1)` becomes a `len(field)` comparison, `Int.Min(1)` a numeric comparison, and `HasPrefix` / `Contains` call `strings.*` with an auto-added import. Parameter prologue validation (automatic checks before your function body) is not emitted yet—use `ensure` explicitly today.
 
 ## Try it
 

docs/resources/roadmap.mdx

@@ -19,12 +19,12 @@ Forst is under active development. This page is a **simplified** view. The canon
 
 | Status | Feature | Notes |
 | --- | --- | --- |
-| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [Shapes and constraints](/language/shapes-and-constraints) | Structural types, built-in constraints, runtime validation at the boundary. |
-| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [`ensure`, `is`, and shape guards](/language/ensure-and-narrowing) | Runtime checks tied to types; shape refinement on records. |
+| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" /> | [Shapes and constraints](/language/shapes-and-constraints) | Structural types and built-in constraints; compile-time checks where values are static, runtime validation via `ensure` in the body today. Parameter prologue emission is future work. |
+| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" /> | [`ensure`, `is`, and shape guards](/language/ensure-and-narrowing) | Runtime checks tied to types; shape refinement on records. Successor narrowing after `ensure` works for simple identifiers; compound paths still open. |
 | <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [Nil and presence checks](/language/ensure-and-narrowing) | `ensure x is Nil()`, `ensure !x`, and `*T` `.Present()` / `.Nil()` on pointers. Not full optional value types yet. |
 | <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" /> | [Type guards](/language/type-guards) | Domain predicates with `is (subject T) Name { … }`; narrowing polish still open. |
 | <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" /> | [Result and nominal errors](/language/errors-and-result) | `Result(S, F)`, `error X { … }`, and `ensure` / `if x is Ok()` narrowing. Closed nominal error unions (`ParseError \| IoError`) emit sealed Go interfaces. Failure-type and export rules still maturing. |
-| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" /> | Control-flow narrowing | If-branch refinement works; join across branches and post-`ensure` narrowing still open. |
+| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" /> | Control-flow narrowing | If-branch refinement works; ensure-successor narrowing for simple identifiers works; compound paths and join across branches still open. |
 | <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" /> | Type aliases | Simple `type Name = BaseType` works end-to-end; broader alias semantics still evolving. |
 | <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" /> | Binary types (`A \| B`, `A & B`) | Union and intersection typedefs type-check; closed nominal error unions emit to Go and TS. General unions, intersections, and narrowing still incomplete. |
 | <Icon icon="calendar" iconType="solid" size={16} color="#64748B" /> | Optional types (`T \| Nil`) | Planned: Crystal-style `T \| Nil` / `T?` unions, narrowing, and Go lowering. See [optionals RFC](https://github.com/forst-lang/forst/tree/main/examples/in/rfc/optionals). |

docs/snippets/ensure-if-ok.mdx

@@ -8,9 +8,10 @@
   </Tab>
   <Tab title="Generated Go">
     ```go
-    // forst build
-    if x, ok := x.(Ok); ok {
-    	println(x.Value)
+    // forst build — Result lowers to (T, error)
+    x, xErr := one()
+    if xErr == nil {
+    	println(x)
     }
     ```
   </Tab>

docs/snippets/type-guards-mutation.mdx

@@ -14,7 +14,7 @@
   </Tab>
   <Tab title="Generated Go">
     ```go
-    // forst build
+    // forst build — illustrative; type-level guards do not emit Go helpers yet
     func G_Input(m MutationArg, input Shape) error {
     	// shape guard: m must include input field
     	return nil

examples/in/union_error_narrowing.ft

@@ -2,7 +2,7 @@ package main
 
 // Narrowing: failure payloads from closed nominal-error unions (ErrKind = A | B) use Result(S, ErrKind)
 // and `Err()` / `Err(...)` guards — not `is ParseError` on the union (nominal errors are not `is` guards).
-// Covered by compiler and typechecker tests; no golden .go (TestExamples skips when out/ is missing).
+// Golden: ../out/union_error_narrowing.go (`task example:union-error-narrowing`, cmd/forst TestExamples).
 
 error ParseError {
 	code: Int,

forst/internal/ast/compound_assign_test.go

@@ -36,6 +36,58 @@ func TestIsAssignmentOperatorToken(t *testing.T) {
 	}
 }
 
+func TestCompoundAssignBinaryOp_allOperators(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		compound TokenIdent
+		binary   TokenIdent
+	}{
+		{TokenMinusEq, TokenMinus},
+		{TokenStarEq, TokenStar},
+		{TokenDivideEq, TokenDivide},
+		{TokenModuloEq, TokenModulo},
+		{TokenBitwiseAndEq, TokenBitwiseAnd},
+		{TokenBitwiseOrEq, TokenBitwiseOr},
+	}
+	for _, tc := range cases {
+		op, ok := CompoundAssignBinaryOp(tc.compound)
+		if !ok || op != tc.binary {
+			t.Fatalf("%s -> %v ok=%v", tc.compound, op, ok)
+		}
+	}
+	if _, ok := CompoundAssignBinaryOp(TokenColonEquals); ok {
+		t.Fatal(":= is not compound assign")
+	}
+}
+
+func TestCompoundAssignOperatorString_allSpellings(t *testing.T) {
+	t.Parallel()
+	cases := map[TokenIdent]string{
+		TokenPlusEq:       "+=",
+		TokenMinusEq:      "-=",
+		TokenStarEq:       "*=",
+		TokenDivideEq:     "/=",
+		TokenModuloEq:     "%=",
+		TokenBitwiseAndEq: "&=",
+		TokenBitwiseOrEq:  "|=",
+	}
+	for tok, want := range cases {
+		if got := CompoundAssignOperatorString(tok); got != want {
+			t.Fatalf("%s: got %q want %q", tok, got, want)
+		}
+	}
+	if got := CompoundAssignOperatorString(TokenPlus); got != string(TokenPlus) {
+		t.Fatalf("unknown token: %q", got)
+	}
+}
+
+func TestIsAssignmentOperatorToken_colonEquals(t *testing.T) {
+	t.Parallel()
+	if !IsAssignmentOperatorToken(Token{Type: TokenColonEquals, Value: ":="}) {
+		t.Fatal("expected := to be assignment operator")
+	}
+}
+
 func TestAssignmentNode_String_compound(t *testing.T) {
 	t.Parallel()
 	a := AssignmentNode{

forst/internal/ast/expression.go

@@ -44,7 +44,7 @@ type IndexExpressionNode struct {
 	Index  ExpressionNode
 }
 
-func (IndexExpressionNode) isExpression() {}
+func (i IndexExpressionNode) isExpression() { _ = i }
 
 // Kind returns the node kind for index expressions.
 func (i IndexExpressionNode) Kind() NodeKind {

forst/internal/ast/for_stmt.go

@@ -7,6 +7,8 @@ import "fmt"
 // Range: IsRange true, RangeX required; RangeKey/RangeValue optional (nil means omitted, as in `for range ch`).
 // Use Ident ID "_" for blank identifiers.
 type ForNode struct {
+	Label *Ident
+
 	Init  Node
 	Cond  ExpressionNode
 	Post  Node

forst/internal/ast/interface_markers_test.go

@@ -22,4 +22,9 @@ func TestInterfaceMarkerMethodsExecute(t *testing.T) {
 	VariableNode{}.isValue()
 	DereferenceNode{}.isValue()
 	ReferenceNode{}.isValue()
+
+	DereferenceNode{}.isExpression()
+	IndexExpressionNode{}.isExpression()
+	OkExprNode{}.isExpression()
+	ErrExprNode{}.isExpression()
 }

forst/internal/ast/param.go

@@ -1,6 +1,9 @@
 package ast
 
-import "fmt"
+import (
+	"fmt"
+	"strings"
+)
 
 // ParamNode is the interface for parameter nodes
 type ParamNode interface {
@@ -55,3 +58,8 @@ func (p SimpleParamNode) GetType() TypeNode {
 func (p DestructuredParamNode) GetType() TypeNode {
 	return p.Type
 }
+
+// GetIdent returns a comma-separated list of destructured field names.
+func (p DestructuredParamNode) GetIdent() string {
+	return strings.Join(p.Fields, ", ")
+}

forst/internal/ast/param_test.go

@@ -16,4 +16,7 @@ func TestDestructuredParamNode_String_Kind_GetType(t *testing.T) {
 	if d.GetType().Ident != TypeInt {
 		t.Fatal(d.GetType())
 	}
+	if d.GetIdent() != "a, b" {
+		t.Fatalf("GetIdent() = %q", d.GetIdent())
+	}
 }

forst/internal/ast/providers_test.go

@@ -60,6 +60,23 @@ func TestIsPublicExportIdent(t *testing.T) {
 	if IsPublicExportIdent("handle") {
 		t.Fatal("handle is not public")
 	}
+	if IsPublicExportIdent("") {
+		t.Fatal("empty ident is not public")
+	}
+}
+
+func TestParamTypesFromFunction_simpleParamsOnly(t *testing.T) {
+	fn := FunctionNode{
+		Params: []ParamNode{
+			SimpleParamNode{Ident: Ident{ID: "a"}, Type: TypeNode{Ident: TypeInt}},
+			DestructuredParamNode{Fields: []string{"x"}, Type: TypeNode{Ident: TypeString}},
+			SimpleParamNode{Ident: Ident{ID: "b"}, Type: TypeNode{Ident: TypeString}},
+		},
+	}
+	types := ParamTypesFromFunction(fn)
+	if len(types) != 2 || types[0].Ident != TypeInt || types[1].Ident != TypeString {
+		t.Fatalf("got %+v", types)
+	}
 }
 
 func TestIsTestingTParamType(t *testing.T) {

forst/internal/ast/result_expr.go

@@ -8,7 +8,7 @@ type OkExprNode struct {
 	Value ExpressionNode
 }
 
-func (OkExprNode) isExpression() {}
+func (o OkExprNode) isExpression() { _ = o }
 
 func (OkExprNode) Kind() NodeKind { return NodeKindOkExpr }
 
@@ -25,7 +25,7 @@ type ErrExprNode struct {
 	Value ExpressionNode
 }
 
-func (ErrExprNode) isExpression() {}
+func (e ErrExprNode) isExpression() { _ = e }
 
 func (ErrExprNode) Kind() NodeKind { return NodeKindErrExpr }
 

forst/internal/ast/shape_format_test.go

@@ -44,6 +44,55 @@ func TestShapeFieldNamesForCompositeEmit_preservesShapeFieldOrder(t *testing.T)
 	}
 }
 
+func TestShapeFieldNode_MethodSignatureString(t *testing.T) {
+	field := ShapeFieldNode{
+		IsMethod: true,
+		MethodParams: []ParamNode{
+			SimpleParamNode{Ident: Ident{ID: "n"}, Type: TypeNode{Ident: TypeInt}},
+		},
+	}
+	if got := field.MethodSignatureString(); got != "(n Int)" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestShapeFieldNamesInOrder_usesFieldOrderWhenSet(t *testing.T) {
+	fields := map[string]ShapeFieldNode{"b": {}, "a": {}}
+	got := ShapeFieldNamesInOrder(fields, []string{"b", "a"})
+	if len(got) != 2 || got[0] != "b" || got[1] != "a" {
+		t.Fatalf("got %v", got)
+	}
+}
+
+func TestShapeFieldNamesForCompositeEmit_skipsOrderEntriesMissingFromPayload(t *testing.T) {
+	payload := map[string]ShapeFieldNode{"only": {Type: &TypeNode{Ident: TypeString}}}
+	shape := &ShapeNode{FieldOrder: []string{"ghost", "only"}}
+	got := ShapeFieldNamesForCompositeEmit(payload, shape)
+	if len(got) != 1 || got[0] != "only" {
+		t.Fatalf("got %v", got)
+	}
+}
+
+func TestShapeFieldNamesForCompositeEmit_appendsExtraPayloadFieldsSorted(t *testing.T) {
+	payload := map[string]ShapeFieldNode{
+		"id":   {Type: &TypeNode{Ident: TypeString}},
+		"extra": {Type: &TypeNode{Ident: TypeInt}},
+	}
+	shape := &ShapeNode{FieldOrder: []string{"id"}}
+	got := ShapeFieldNamesForCompositeEmit(payload, shape)
+	if len(got) != 2 || got[0] != "id" || got[1] != "extra" {
+		t.Fatalf("got %v", got)
+	}
+}
+
+func TestShapeFieldNamesForCompositeEmit_nilShapeUsesSortedOrder(t *testing.T) {
+	payload := map[string]ShapeFieldNode{"z": {}, "a": {}}
+	got := ShapeFieldNamesForCompositeEmit(payload, nil)
+	if len(got) != 2 || got[0] != "a" || got[1] != "z" {
+		t.Fatalf("got %v", got)
+	}
+}
+
 func TestShapeFieldNamesInOrder_sortsWhenUnspecified(t *testing.T) {
 	fields := map[string]ShapeFieldNode{
 		"z": {},

forst/internal/ast/shape_test.go

@@ -78,6 +78,47 @@ func TestShapeNode_String_multiple_top_level_fields(t *testing.T) {
 	}
 }
 
+func TestShapeFieldNode_IsMethodField_and_methodString(t *testing.T) {
+	field := ShapeFieldNode{
+		IsMethod: true,
+		MethodParams: []ParamNode{
+			SimpleParamNode{Ident: Ident{ID: "msg"}, Type: TypeNode{Ident: TypeString}},
+		},
+		MethodReturnTypes: []TypeNode{{Ident: TypeError}},
+	}
+	if !field.IsMethodField() {
+		t.Fatal("expected method field")
+	}
+	if got := field.String(); got != "(msg String): Error" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestShapeNode_IsMethodOnlyContract_emptyFields(t *testing.T) {
+	if (ShapeNode{Fields: map[string]ShapeFieldNode{}}).IsMethodOnlyContract() {
+		t.Fatal("empty shape is not method-only")
+	}
+}
+
+func TestShapeFieldNode_ValueExpression_fromNode(t *testing.T) {
+	lit := StringLiteralNode{Value: "wired"}
+	field := ShapeFieldNode{Node: lit}
+	expr, ok := field.ValueExpression()
+	if !ok {
+		t.Fatal("expected expression from Node")
+	}
+	if got, ok := expr.(StringLiteralNode); !ok || got.Value != "wired" {
+		t.Fatalf("got %#v", expr)
+	}
+}
+
+func TestShapeFieldNode_ValueExpression_nonExpressionNode(t *testing.T) {
+	field := ShapeFieldNode{Node: CommentNode{Text: "note"}}
+	if _, ok := field.ValueExpression(); ok {
+		t.Fatal("comment node is not an expression")
+	}
+}
+
 func TestShapeNode_String_field_assertion_branch(t *testing.T) {
 	bt := TypeIdent("Str")
 	s := ShapeNode{Fields: map[string]ShapeFieldNode{

forst/internal/ast/type_test.go

@@ -179,6 +179,20 @@ func TestTypeNode_String_each_simple_builtin_switch_case(t *testing.T) {
 	}
 }
 
+func TestNewChannelType_andString(t *testing.T) {
+	t.Parallel()
+	ch := NewChannelType(NewBuiltinType(TypeInt))
+	if ch.Ident != TypeChannel || len(ch.TypeParams) != 1 || ch.TypeParams[0].Ident != TypeInt {
+		t.Fatalf("got %+v", ch)
+	}
+	if got := ch.String(); got != "chan Int" {
+		t.Fatalf("got %q", got)
+	}
+	if got := (TypeNode{Ident: TypeChannel}).String(); got != "chan" {
+		t.Fatalf("got %q", got)
+	}
+}
+
 func TestTypeNode_String_default_branch_multiple_type_params(t *testing.T) {
 	tn := TypeNode{
 		Ident:    "Pair",