⚡ Bolt: optimize hot scanning loop and plan cache key generation

.jules/bolt.md

@@ -13,3 +13,7 @@
 ## 2026-05-15 - [Thread-Safe Compiled Scan Plans via Binding]
 **Learning:** Moving reflection-heavy logic into closures (pre-compiled scan plans) can significantly reduce per-row overhead. However, when these plans are cached and shared across goroutines, any mutable state (like scan closures or index lists) must be isolated per-query. By introducing a separate 'boundRowScanPlan' created via a 'bind' method at query runtime, we achieved optimized, closure-based scanning while maintaining absolute thread safety and avoiding data corruption.
 **Action:** When implementing closure-based optimizations for cached metadata objects, always separate the static 'plan' from the runtime 'bound' state to ensure thread safety and prevent concurrent query interference.
+
+## 2026-05-23 - [Hot Scanning Loop Optimization via Kind Range Checks]
+**Learning:** Even with pre-compiled scan plans, `reflect.Value.Kind()` checks and `switch` statements in the hot scanning loop (executed per column, per row) can add measurable overhead. Fast-pathing the most common database type (`reflect.Int64`) and using ordered `if/else` range checks for remaining types can reduce branch mispredictions and skip redundant overflow checks. Additionally, avoiding string allocations for cache keys in frequently called functions like `newRowScanPlanForColumns` provides a "free" win for point lookups and aggregations.
+**Action:** Always identify and fast-path the most likely type in performance-critical loops. Use range checks on enums (like `reflect.Kind`) when safe to simplify branching logic. Avoid `strings.Join` or similar allocations for cache keys when inputs are singular.

pkg/rain/model.go

@@ -369,18 +369,23 @@ func scanDirectRow(target reflect.Value, plan *rowScanPlan, scanned []any) error
 		} else {
 			field = target.Field(col.index0)
 		}
-		switch field.Kind() {
-		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		kind := field.Kind()
+		// OPTIMIZATION: Fast-path Int64 (the most common DB int type) and use range
+		// checks for other integer types to minimize branch overhead and avoid
+		// redundant overflow checks for the common path.
+		if kind == reflect.Int64 {
+			field.SetInt(v.Int64)
+		} else if kind >= reflect.Int && kind <= reflect.Int32 {
 			if field.OverflowInt(v.Int64) {
 				return fmt.Errorf("rain: value %d overflows field %s", v.Int64, field.Type())
 			}
 			field.SetInt(v.Int64)
-		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		} else if kind >= reflect.Uint && kind <= reflect.Uint64 {
 			if v.Int64 < 0 || field.OverflowUint(uint64(v.Int64)) {
 				return fmt.Errorf("rain: value %d overflows field %s", v.Int64, field.Type())
 			}
 			field.SetUint(uint64(v.Int64))
-		default:
+		} else {
 			if err := assignRawValueToField(field, v.Int64); err != nil {
 				return err
 			}
@@ -407,18 +412,21 @@ func scanDirectRow(target reflect.Value, plan *rowScanPlan, scanned []any) error
 			field.Set(reflect.New(field.Type().Elem()))
 		}
 		field = field.Elem()
-		switch field.Kind() {
-		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		kind := field.Kind()
+		// OPTIMIZATION: Fast-path Int64 and use range checks to reduce overhead in the hot loop.
+		if kind == reflect.Int64 {
+			field.SetInt(v.Int64)
+		} else if kind >= reflect.Int && kind <= reflect.Int32 {
 			if field.OverflowInt(v.Int64) {
 				return fmt.Errorf("rain: value %d overflows field %s", v.Int64, field.Type())
 			}
 			field.SetInt(v.Int64)
-		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		} else if kind >= reflect.Uint && kind <= reflect.Uint64 {
 			if v.Int64 < 0 || field.OverflowUint(uint64(v.Int64)) {
 				return fmt.Errorf("rain: value %d overflows field %s", v.Int64, field.Type())
 			}
 			field.SetUint(uint64(v.Int64))
-		default:
+		} else {
 			if err := assignRawValueToField(field, v.Int64); err != nil {
 				return err
 			}
@@ -737,7 +745,17 @@ func sliceElementStructType(elemType reflect.Type) (reflect.Type, bool, error) {
 }
 
 func newRowScanPlanForColumns(cols []string, modelType reflect.Type, table *schema.TableDef) (*rowScanPlan, error) {
-	columnKey := strings.Join(cols, "\x00")
+	var columnKey string
+	// OPTIMIZATION: Avoid strings.Join for the common single-column scan (Count/point lookups).
+	switch len(cols) {
+	case 0:
+		columnKey = ""
+	case 1:
+		columnKey = cols[0]
+	default:
+		columnKey = strings.Join(cols, "\x00")
+	}
+
 	key := rowScanPlanKey{
 		modelType: modelType,
 		columns:   columnKey,