Add step reference validation for conditions

  Validate that step references in conditions (steps.foo) point to steps
  that exist and come before the current step. This catches forward
  references, self-references, and typos at validation time.

  Compile (compile.go):
  - Add stepRefFinder AST visitor to find steps.X patterns
  - Add ExtractStepRefs() to extract step names from expressions
  - Handle both dot notation (steps.foo) and bracket notation (steps["foo"])

  Validation (validate.go):
  - Add validateStepRefs() to check step references
  - Detect unknown steps, forward references, and self-references
  - Expand aliases to check step refs hidden in alias definitions
  - Distinct error messages for each case

  Documentation (README.md):
  - Add "Step references" paragraph in Condition Expressions section

  Tests:
  - Add TestExtractStepRefs with 8 cases (dot, bracket, string literal, dedup)
  - Add TestValidate_StepReferences with 6 cases (valid, unknown, forward, alias, self, multiple)

Author: abgoyal

README.md

@@ -1778,6 +1778,8 @@ Aliases are expanded at compile time, so `"found && is_owner"` becomes `"(steps.
 
 **Division safety:** Conditions with dynamic divisors must use `divOr(a, b, fallback)` instead of `a / b`. This prevents runtime panics from division by zero. Division by literal non-zero values (e.g., `x / 2`) is allowed. Violations are caught at workflow compile time.
 
+**Step references:** Conditions using `steps.X` are validated at compile time. Steps can only reference results from earlier steps - forward references and self-references are errors. Unknown step names are also caught.
+
 ### Error Handling
 
 Control step failure behavior with `on_error`:

TESTS.md

@@ -564,6 +564,7 @@ Run `make test-cover` for current coverage statistics.
 - **TestExprFunc_isValidPublicID**: TestExprFunc_isValidPublicID tests the isValidPublicID expr function.
 - **TestExprFuncs_InConditions**: TestExprFuncs_InConditions tests that common functions from tmpl.ExprFuncs
 - **TestValidateDivisions**: TestValidateDivisions tests static validation of division operations
+- **TestExtractStepRefs**: TestExtractStepRefs tests step reference extraction from expressions
 
 ### config_test.go
 
@@ -699,6 +700,7 @@ Run `make test-cover` for current coverage statistics.
 - **TestValidate_HTTPCallRetry**: TestValidate_HTTPCallRetry verifies httpcall retry configuration validation
 - **TestValidate_HTTPCallRetryValid**: TestValidate_HTTPCallRetryValid verifies valid httpcall retry configuration passes
 - **TestValidate_DivisionSafety**: TestValidate_DivisionSafety tests that unsafe divisions are caught during validation
+- **TestValidate_StepReferences**: TestValidate_StepReferences tests that step references are validated
 
 
 ---

internal/config/static_template.go

@@ -193,5 +193,3 @@ func filterDynamicPaths(paths []string) []string {
 	}
 	return dynamic
 }
-
-

internal/tmpl/engine_test.go

@@ -1778,7 +1778,7 @@ func TestPrivateIDFunc(t *testing.T) {
 		{"wrong namespace prefix", "order", validPublicID, true, "invalid prefix"},
 		{"invalid base62 characters", "user", "usr_!@#$%^&*()", true, "invalid"},
 		{"empty public ID", "user", "", true, "invalid prefix"},
-		{"prefix only error", "user", "usr_", true, "invalid length"},     // Empty encoded part rejected
+		{"prefix only error", "user", "usr_", true, "invalid length"}, // Empty encoded part rejected
 		{"missing prefix separator", "user", "usr00000000001", true, "invalid prefix"},
 		{"too short encoded part", "user", "usr_abc", true, "invalid length"}, // Must be exactly 11 chars
 		{"no prefix configured namespace", "order", "ord_" + strings.Repeat("0", 11), false, ""},

internal/workflow/compile.go

@@ -684,6 +684,64 @@ func ValidateDivisions(exprStr string) error {
 	return nil
 }
 
+// stepRefFinder is a visitor that collects step names referenced via steps.X patterns.
+type stepRefFinder struct {
+	refs []string
+	seen map[string]bool
+}
+
+func (f *stepRefFinder) Visit(node *ast.Node) {
+	if node == nil || *node == nil {
+		return
+	}
+
+	// Look for member access patterns: steps.foo or steps["foo"]
+	member, ok := (*node).(*ast.MemberNode)
+	if !ok {
+		return
+	}
+
+	// Check if the object is the "steps" identifier
+	ident, ok := member.Node.(*ast.IdentifierNode)
+	if !ok || ident.Value != "steps" {
+		return
+	}
+
+	// Extract the step name from the property
+	var stepName string
+	switch prop := member.Property.(type) {
+	case *ast.StringNode:
+		// steps["foo"]
+		stepName = prop.Value
+	case *ast.IdentifierNode:
+		// steps.foo
+		stepName = prop.Value
+	default:
+		// Dynamic access like steps[variable] - can't validate statically
+		return
+	}
+
+	if stepName != "" && !f.seen[stepName] {
+		f.refs = append(f.refs, stepName)
+		f.seen[stepName] = true
+	}
+}
+
+// ExtractStepRefs finds step names referenced in an expression via steps.X patterns.
+// Returns a list of step names that are accessed (e.g., "fetch" from "steps.fetch.count > 0").
+func ExtractStepRefs(exprStr string) ([]string, error) {
+	tree, err := parser.Parse(exprStr)
+	if err != nil {
+		return nil, err
+	}
+
+	finder := &stepRefFinder{
+		seen: make(map[string]bool),
+	}
+	ast.Walk(&tree.Node, finder)
+	return finder.refs, nil
+}
+
 // EvalCondition evaluates a compiled condition against an environment.
 func EvalCondition(prog *vm.Program, env map[string]any) (bool, error) {
 	result, err := vm.Run(prog, env)

internal/workflow/compile_test.go

@@ -1546,3 +1546,79 @@ func TestValidateDivisions(t *testing.T) {
 		}
 	})
 }
+
+// TestExtractStepRefs tests step reference extraction from expressions
+func TestExtractStepRefs(t *testing.T) {
+	tests := []struct {
+		name     string
+		expr     string
+		expected []string
+	}{
+		{
+			name:     "simple step reference",
+			expr:     "steps.fetch.count > 0",
+			expected: []string{"fetch"},
+		},
+		{
+			name:     "multiple step references",
+			expr:     "steps.auth.valid && steps.fetch.count > 0",
+			expected: []string{"auth", "fetch"},
+		},
+		{
+			name:     "nested property access",
+			expr:     "steps.fetch.row.user_id == steps.auth.row.id",
+			expected: []string{"fetch", "auth"},
+		},
+		{
+			name:     "no step references",
+			expr:     "trigger.params.id != \"\"",
+			expected: []string{},
+		},
+		{
+			name:     "bracket notation",
+			expr:     `steps["my-step"].count > 0`,
+			expected: []string{"my-step"},
+		},
+		{
+			name:     "mixed dot and bracket",
+			expr:     `steps.fetch.count > 0 && steps["other"].valid`,
+			expected: []string{"fetch", "other"},
+		},
+		{
+			name:     "steps in string literal not extracted",
+			expr:     `name == "steps.foo"`,
+			expected: []string{},
+		},
+		{
+			name:     "duplicate refs deduplicated",
+			expr:     "steps.fetch.count > 0 && steps.fetch.valid",
+			expected: []string{"fetch"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			refs, err := ExtractStepRefs(tt.expr)
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+
+			// Check length
+			if len(refs) != len(tt.expected) {
+				t.Errorf("expected %d refs, got %d: %v", len(tt.expected), len(refs), refs)
+				return
+			}
+
+			// Check each expected ref is present
+			refSet := make(map[string]bool)
+			for _, r := range refs {
+				refSet[r] = true
+			}
+			for _, exp := range tt.expected {
+				if !refSet[exp] {
+					t.Errorf("expected ref %q not found in %v", exp, refs)
+				}
+			}
+		})
+	}
+}

internal/workflow/validate.go

@@ -95,7 +95,7 @@ func Validate(cfg *WorkflowConfig, ctx *ValidationContext) *ValidationResult {
 			stepNames[step.Name] = i
 		}
 
-		validateStep(&step, stepPrefix, stepNames, ctx, r)
+		validateStep(&step, stepPrefix, i, stepNames, cfg.Conditions, ctx, r)
 
 		// Track response steps
 		if step.IsResponse() {
@@ -285,11 +285,14 @@ func validateRateLimit(cfg *RateLimitRefConfig, prefix string, ctx *ValidationCo
 	}
 }
 
-func validateStep(cfg *StepConfig, prefix string, stepNames map[string]int, ctx *ValidationContext, r *ValidationResult) {
-	// Validate condition syntax
+func validateStep(cfg *StepConfig, prefix string, stepIndex int, stepNames map[string]int, aliases map[string]string, ctx *ValidationContext, r *ValidationResult) {
+	// Validate condition syntax and step references
 	if cfg.Condition != "" {
 		if err := validateExprSyntax(cfg.Condition); err != nil {
 			r.addError("%s.condition: invalid expression: %v", prefix, err)
+		} else {
+			// Validate step references in condition
+			validateStepRefs(cfg.Condition, prefix+".condition", stepIndex, stepNames, aliases, r)
 		}
 	}
 
@@ -335,7 +338,7 @@ func validateStep(cfg *StepConfig, prefix string, stepNames map[string]int, ctx
 	case "response":
 		validateResponseStep(cfg, prefix, r)
 	case "block":
-		validateBlockStep(cfg, prefix, stepNames, ctx, r)
+		validateBlockStep(cfg, prefix, stepNames, aliases, ctx, r)
 	}
 }
 
@@ -402,7 +405,7 @@ func validateResponseStep(cfg *StepConfig, prefix string, r *ValidationResult) {
 	}
 }
 
-func validateBlockStep(cfg *StepConfig, prefix string, parentStepNames map[string]int, ctx *ValidationContext, r *ValidationResult) {
+func validateBlockStep(cfg *StepConfig, prefix string, parentStepNames map[string]int, aliases map[string]string, ctx *ValidationContext, r *ValidationResult) {
 	// Validate iterate if present
 	if cfg.Iterate != nil {
 		iterPrefix := prefix + ".iterate"
@@ -445,7 +448,7 @@ func validateBlockStep(cfg *StepConfig, prefix string, parentStepNames map[strin
 			continue
 		}
 
-		validateStep(&step, stepPrefix, nestedNames, ctx, r)
+		validateStep(&step, stepPrefix, i, nestedNames, aliases, ctx, r)
 	}
 
 	// Validate outputs reference valid step names or special values
@@ -482,6 +485,60 @@ func validateExprSyntax(exprStr string) error {
 	return nil
 }
 
+// validateStepRefs validates step references in an expression.
+// Checks that referenced steps exist and come before the current step.
+func validateStepRefs(exprStr, prefix string, currentStepIndex int, stepNames map[string]int, aliases map[string]string, r *ValidationResult) {
+	// Collect all step refs from the expression and any aliases it uses
+	allRefs := make(map[string]bool)
+
+	// Extract direct step refs from expression
+	refs, err := ExtractStepRefs(exprStr)
+	if err != nil {
+		// Syntax errors already caught by validateExprSyntax
+		return
+	}
+	for _, ref := range refs {
+		allRefs[ref] = true
+	}
+
+	// Find aliases used in expression and extract their step refs too
+	if len(aliases) > 0 {
+		aliasNames := make(map[string]bool, len(aliases))
+		for name := range aliases {
+			aliasNames[name] = true
+		}
+
+		usedAliases, err := extractAliasRefs(exprStr, aliasNames)
+		if err != nil {
+			return
+		}
+
+		// For each used alias, extract step refs from its source
+		for _, aliasName := range usedAliases {
+			aliasSource := aliases[aliasName]
+			aliasRefs, err := ExtractStepRefs(aliasSource)
+			if err != nil {
+				continue
+			}
+			for _, ref := range aliasRefs {
+				allRefs[ref] = true
+			}
+		}
+	}
+
+	// Validate each step reference
+	for stepRef := range allRefs {
+		refIndex, exists := stepNames[stepRef]
+		if !exists {
+			r.addError("%s: references unknown step '%s'", prefix, stepRef)
+		} else if refIndex == currentStepIndex {
+			r.addError("%s: step cannot reference itself ('%s')", prefix, stepRef)
+		} else if refIndex > currentStepIndex {
+			r.addError("%s: references step '%s' which comes after current step (forward reference)", prefix, stepRef)
+		}
+	}
+}
+
 // pathParamRegex matches path parameters like {id} or {user_id}
 var pathParamRegex = regexp.MustCompile(`\{([a-zA-Z_][a-zA-Z0-9_]*)\}`)