Add DSL guardrails: type checking, name validation, guard verification

Catches errors at .btw build time instead of at Solidity compile time:

- Duplicate names: registers, events, functions with same name
- Reserved names: schema/register/function names that conflict with
  Solidity keywords (function, event, mapping), built-ins (msg, block),
  forge-std (Test, Script), or generated internals (contractOwner)
- Arc type mismatch: indexing a scalar register X[key], or wrong
  key depth on nested maps (1 key on a map[address,address]uint256)
- Unknown registers in arcs: NOPE -|amount|> fn
- Unknown identifiers in guards: require(NOPE >= amount)
- Undeclared events: @event NoSuchEvent
- Unknown types: register X maps[address]uint256 (typo)

10 test cases in TestValidation covering each guardrail.
All existing examples and tests still pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: stackdump

dsl/builder.go

@@ -83,9 +83,237 @@ func Build(ast *Schema) (*metamodel.Schema, error) {
 		}
 	}
 
+	// Validate the built schema
+	if err := validate(ast, s); err != nil {
+		return nil, err
+	}
+
 	return s, nil
 }
 
+// validate checks the DSL AST and built schema for common errors.
+func validate(ast *Schema, s *metamodel.Schema) error {
+	// Build lookup tables
+	registers := make(map[string]Register)
+	for _, r := range ast.Registers {
+		registers[r.Name] = r
+	}
+
+	fnVars := make(map[string]map[string]bool) // fn name → var names
+	for _, fn := range ast.Functions {
+		vars := make(map[string]bool)
+		for _, v := range fn.Vars {
+			vars[v.Name] = true
+		}
+		fnVars[fn.Name] = vars
+	}
+
+	// 1. Duplicate detection
+	{
+		seen := make(map[string]string) // name → kind
+		for _, r := range ast.Registers {
+			if prev, ok := seen[r.Name]; ok {
+				return fmt.Errorf("duplicate name %q (already declared as %s)", r.Name, prev)
+			}
+			seen[r.Name] = "register"
+		}
+		for _, e := range ast.Events {
+			if prev, ok := seen[e.Name]; ok {
+				return fmt.Errorf("duplicate name %q (already declared as %s)", e.Name, prev)
+			}
+			seen[e.Name] = "event"
+		}
+		for _, f := range ast.Functions {
+			if prev, ok := seen[f.Name]; ok {
+				return fmt.Errorf("duplicate name %q (already declared as %s)", f.Name, prev)
+			}
+			seen[f.Name] = "function"
+		}
+	}
+
+	// 2. Reserved name checking
+	if err := checkReservedName(ast.Name, "schema"); err != nil {
+		return err
+	}
+	for _, r := range ast.Registers {
+		if err := checkReservedName(r.Name, "register"); err != nil {
+			return err
+		}
+	}
+	for _, f := range ast.Functions {
+		if err := checkReservedName(f.Name, "function"); err != nil {
+			return err
+		}
+	}
+
+	// 3. Arc type checking
+	for _, fn := range ast.Functions {
+		for _, arc := range fn.Arcs {
+			// Determine the place side (not the function side)
+			placeName := arc.Source
+			indices := arc.SourceIndices
+			if arc.Source == fn.Name {
+				placeName = arc.Target
+				indices = arc.TargetIndices
+			}
+
+			reg, ok := registers[placeName]
+			if !ok {
+				// Arc references a non-existent register
+				return fmt.Errorf("function %s: arc references unknown register %q", fn.Name, placeName)
+			}
+
+			mapDepth := mapKeyDepth(reg.Type)
+			indexCount := len(indices)
+
+			if mapDepth == 0 && indexCount > 0 {
+				return fmt.Errorf("function %s: register %s is %s (scalar), cannot index with [%s]",
+					fn.Name, reg.Name, reg.Type, strings.Join(indices, "]["))
+			}
+
+			if indexCount > 0 && indexCount != mapDepth {
+				return fmt.Errorf("function %s: register %s needs %d index key(s) (type %s), got %d",
+					fn.Name, reg.Name, mapDepth, reg.Type, indexCount)
+			}
+		}
+	}
+
+	// 4. Guard variable validation
+	for _, fn := range ast.Functions {
+		if fn.Require == "" {
+			continue
+		}
+		vars := fnVars[fn.Name]
+		if err := validateGuardIdents(fn.Name, fn.Require, registers, vars); err != nil {
+			return err
+		}
+	}
+
+	// 5. Event reference validation
+	eventNames := make(map[string]bool)
+	for _, e := range ast.Events {
+		eventNames[e.Name] = true
+	}
+	for _, fn := range ast.Functions {
+		if fn.EventRef != "" && !eventNames[fn.EventRef] {
+			return fmt.Errorf("function %s: @event references undeclared event %q", fn.Name, fn.EventRef)
+		}
+	}
+
+	return nil
+}
+
+// checkReservedName returns an error if the name conflicts with Solidity or Foundry.
+func checkReservedName(name, kind string) error {
+	reserved := map[string]string{
+		// Solidity keywords
+		"function": "Solidity keyword", "event": "Solidity keyword",
+		"mapping": "Solidity keyword", "constructor": "Solidity keyword",
+		"require": "Solidity keyword", "revert": "Solidity keyword",
+		"assert": "Solidity keyword", "return": "Solidity keyword",
+		"if": "Solidity keyword", "else": "Solidity keyword",
+		"for": "Solidity keyword", "while": "Solidity keyword",
+		"true": "Solidity keyword", "false": "Solidity keyword",
+		// Solidity built-in variables
+		"msg": "Solidity built-in", "block": "Solidity built-in",
+		"tx": "Solidity built-in", "this": "Solidity built-in",
+		// Forge-std conflicts
+		"Test": "forge-std class", "Script": "forge-std class",
+		"Vm": "forge-std class", "console": "forge-std class",
+		// Generated contract internals
+		"contractOwner": "generated internal", "currentEpoch": "generated internal",
+		"eventSequence": "generated internal",
+	}
+	if reason, ok := reserved[name]; ok {
+		return fmt.Errorf("%s name %q conflicts with %s", kind, name, reason)
+	}
+	return nil
+}
+
+// mapKeyDepth returns the nesting depth of a map type.
+// "uint256" → 0, "map[address]uint256" → 1, "map[address]map[address]uint256" → 2
+func mapKeyDepth(typ string) int {
+	depth := 0
+	remaining := typ
+	for strings.HasPrefix(remaining, "map[") {
+		close := strings.Index(remaining, "]")
+		if close == -1 {
+			break
+		}
+		depth++
+		remaining = remaining[close+1:]
+	}
+	return depth
+}
+
+// validateGuardIdents checks that all identifiers in a guard expression
+// are known registers, function variables, or built-in names.
+func validateGuardIdents(fnName, guard string, registers map[string]Register, vars map[string]bool) error {
+	// Extract identifiers from the guard using simple scanning
+	// (avoid importing guard package to prevent circular deps)
+	idents := extractIdents(guard)
+
+	builtins := map[string]bool{
+		"caller": true, "address": true, "true": true, "false": true,
+		"msg": true, "sender": true, // for msg.sender
+	}
+
+	for _, id := range idents {
+		if builtins[id] {
+			continue
+		}
+		if _, ok := registers[id]; ok {
+			continue
+		}
+		if vars[id] {
+			continue
+		}
+		// Allow numeric literals
+		if isNumeric(id) {
+			continue
+		}
+		// Allow known function-like calls (vestedAmount, etc.)
+		// These are generated helper functions, not user-defined
+		if strings.Contains(guard, id+"(") {
+			continue
+		}
+		return fmt.Errorf("function %s: guard references unknown identifier %q", fnName, id)
+	}
+	return nil
+}
+
+// extractIdents returns all identifier-like tokens from an expression string.
+func extractIdents(expr string) []string {
+	var idents []string
+	i := 0
+	for i < len(expr) {
+		if isLetter(expr[i]) || expr[i] == '_' {
+			start := i
+			for i < len(expr) && (isLetter(expr[i]) || isDigit(expr[i]) || expr[i] == '_' || expr[i] == '.') {
+				i++
+			}
+			idents = append(idents, expr[start:i])
+		} else {
+			i++
+		}
+	}
+	return idents
+}
+
+func isLetter(c byte) bool { return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') }
+func isDigit(c byte) bool  { return c >= '0' && c <= '9' }
+func isNumeric(s string) bool {
+	if len(s) == 0 {
+		return false
+	}
+	for _, c := range s {
+		if c < '0' || c > '9' {
+			return false
+		}
+	}
+	return true
+}
+
 // buildArc converts a DSL Arc into a metamodel.Arc.
 // The function name determines direction:
 //   - PLACE -|w|> fnName  =>  input arc (Source=PLACE, Target=fnName)

dsl/dsl_test.go

@@ -1,6 +1,7 @@
 package dsl
 
 import (
+	"strings"
 	"testing"
 )
 
@@ -526,3 +527,91 @@ schema Test {
 		t.Errorf("expected map[uint256]map[address]map[uint256]bool, got %s", ast.Registers[1].Type)
 	}
 }
+
+func TestValidation(t *testing.T) {
+	cases := []struct {
+		name string
+		src  string
+		want string // substring of expected error
+	}{
+		{
+			name: "duplicate register",
+			src:  `schema Foo { version "1.0" register X uint256 register X uint256 }`,
+			want: `duplicate name "X"`,
+		},
+		{
+			name: "reserved schema name",
+			src:  `schema Test { version "1.0" }`,
+			want: `schema name "Test" conflicts with forge-std class`,
+		},
+		{
+			name: "reserved function name",
+			src:  `schema Foo { version "1.0" register X uint256 fn(msg) { X -|1|> msg } }`,
+			want: `function name "msg" conflicts with Solidity built-in`,
+		},
+		{
+			name: "scalar indexed",
+			src:  `schema Foo { version "1.0" register X uint256 fn(f) { var k address X[k] -|1|> f } }`,
+			want: "register X is uint256 (scalar), cannot index",
+		},
+		{
+			name: "unknown register in arc",
+			src:  `schema Foo { version "1.0" fn(f) { var x amount NOPE -|x|> f } }`,
+			want: `unknown register "NOPE"`,
+		},
+		{
+			name: "unknown identifier in guard",
+			src:  `schema Foo { version "1.0" register X uint256 fn(f) { var amount amount require(NOPE >= amount) f -|amount|> X } }`,
+			want: `guard references unknown identifier "NOPE"`,
+		},
+		{
+			name: "undeclared event",
+			src:  `schema Foo { version "1.0" register X uint256 fn(f) { var amount amount @event Nope f -|amount|> X } }`,
+			want: `undeclared event "Nope"`,
+		},
+		{
+			name: "unknown type",
+			src:  `schema Foo { version "1.0" register X maps[address]uint256 }`,
+			want: `unknown type "maps"`,
+		},
+		{
+			name: "map key depth mismatch",
+			src:  `schema Foo { version "1.0" register X map[address,address]uint256 fn(f) { var k address X[k] -|1|> f } }`,
+			want: "needs 2 index key(s)",
+		},
+		{
+			name: "valid schema passes",
+			src: `schema Foo { version "1.0"
+				register X map[address]uint256 observable
+				event E { to: address indexed amount: uint256 }
+				fn(inc) { var to address var amount amount @event E inc -|amount|> X[to] }
+			}`,
+			want: "", // no error
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			ast, err := Parse(tc.src)
+			if err != nil {
+				if tc.want != "" && strings.Contains(err.Error(), tc.want) {
+					return // parse error matches expected
+				}
+				t.Fatalf("unexpected parse error: %v", err)
+			}
+			_, err = Build(ast)
+			if tc.want == "" {
+				if err != nil {
+					t.Fatalf("expected no error, got: %v", err)
+				}
+				return
+			}
+			if err == nil {
+				t.Fatalf("expected error containing %q, got nil", tc.want)
+			}
+			if !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("expected error containing %q, got: %v", tc.want, err)
+			}
+		})
+	}
+}

dsl/parser.go

@@ -218,6 +218,9 @@ func (p *Parser) parseTypeString() (string, error) {
 	// Check for map[...] type
 	// Supports: map[address]uint256, map[address]map[address]uint256,
 	// and shorthand: map[address,address]uint256 → map[address]map[address]uint256
+	if tok.Value != "map" && !isKnownType(tok.Value) {
+		return "", fmt.Errorf("line %d: unknown type %q (expected uint256, address, bool, or map[...])", tok.Line, tok.Value)
+	}
 	if tok.Value == "map" && p.peek().Type == TokenLBracket {
 		p.advance() // [
 		// Collect comma-separated key types
@@ -492,3 +495,14 @@ func (p *Parser) parsePlaceRef() (string, []string, error) {
 
 	return nameTok.Value, indices, nil
 }
+
+// isKnownType returns true for valid Solidity-compatible type names.
+func isKnownType(t string) bool {
+	known := map[string]bool{
+		"uint256": true, "uint128": true, "uint64": true, "uint32": true, "uint16": true, "uint8": true,
+		"int256": true, "int128": true, "int64": true, "int32": true, "int16": true, "int8": true,
+		"address": true, "bool": true, "bytes32": true, "bytes": true, "string": true,
+		"amount": true, // DSL shorthand for uint256
+	}
+	return known[t]
+}

internal/server/server_test.go

@@ -278,7 +278,7 @@ func TestPostSVG(t *testing.T) {
 
 func TestCompile(t *testing.T) {
 	srv := testServer(t)
-	btw := `schema Test {
+	btw := `schema Counter {
   version "1.0"
   register balance uint256 observable
   fn(inc) {
@@ -295,7 +295,7 @@ func TestCompile(t *testing.T) {
 	}
 	var resp map[string]interface{}
 	json.Unmarshal(w.Body.Bytes(), &resp)
-	if resp["name"] != "Test" {
-		t.Fatalf("expected name=Test, got %v", resp["name"])
+	if resp["name"] != "Counter" {
+		t.Fatalf("expected name=Counter, got %v", resp["name"])
 	}
 }