[bal-devnet-3] cmd/utils, node/cli: add --exec.serial flag to clamp workers to 1 (#20863)

Cherry-pick of #20853 to bal-devnet-3. Depends on #20862 (#20797
cherry-pick).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mh0lt

cmd/utils/flags.go

@@ -1165,6 +1165,11 @@ var (
 		Usage: "Parallel executor worker count (equivalent to EXEC3_WORKERS). Default: half the number of CPU cores, other half reserved for snapshots build/merge/prune.",
 		Value: runtime.NumCPU() / 2,
 	}
+	ExecSerialFlag = cli.BoolFlag{
+		Name:  "exec.serial",
+		Usage: "Force serial execution by clamping the parallel executor to a single worker. Wins over --exec.workers and EXEC3_WORKERS — use to disable parallelism for diagnostics or like-for-like baseline comparisons.",
+		Value: false,
+	}
 	ExecNoMergeFlag = cli.BoolFlag{
 		Name:  "exec.no-merge",
 		Usage: "Disable state-aggregator file merges for Domain / History / Inverted-Index (equivalent to NO_MERGE=true). Diagnostic / perf-comparison use only.",
@@ -2003,6 +2008,11 @@ func SetEthConfig(ctx *cli.Context, nodeConfig *nodecfg.Config, cfg *ethconfig.C
 		dbg.SetExec3Workers(n)
 		cfg.ExecWorkerCount = n
 	}
+	// --exec.serial wins over --exec.workers / EXEC3_WORKERS: clamp to 1.
+	if ctx.IsSet(ExecSerialFlag.Name) && ctx.Bool(ExecSerialFlag.Name) {
+		dbg.SetExec3Workers(1)
+		cfg.ExecWorkerCount = 1
+	}
 	if ctx.IsSet(ExecNoMergeFlag.Name) {
 		dbg.SetNoMerge(ctx.Bool(ExecNoMergeFlag.Name))
 	}

cmd/utils/flags_test.go

@@ -132,6 +132,9 @@ func TestExecPerfFlags_OverrideDbg(t *testing.T) {
 		if ctx.IsSet(ExecWorkersFlag.Name) {
 			dbg.SetExec3Workers(ctx.Int(ExecWorkersFlag.Name))
 		}
+		if ctx.IsSet(ExecSerialFlag.Name) && ctx.Bool(ExecSerialFlag.Name) {
+			dbg.SetExec3Workers(1)
+		}
 		if ctx.IsSet(ExecNoMergeFlag.Name) {
 			dbg.SetNoMerge(ctx.Bool(ExecNoMergeFlag.Name))
 		}
@@ -145,7 +148,7 @@ func TestExecPerfFlags_OverrideDbg(t *testing.T) {
 		app := cli.NewApp()
 		app.Flags = []cli.Flag{
 			&ExecBatchedIOFlag, &ExecStateCacheFlag, &ExecWorkersFlag,
-			&ExecNoMergeFlag, &ExecNoPruneFlag,
+			&ExecSerialFlag, &ExecNoMergeFlag, &ExecNoPruneFlag,
 		}
 		app.Action = apply
 		require.NoError(t, app.Run(append([]string{"test"}, args...)))
@@ -195,6 +198,26 @@ func TestExecPerfFlags_OverrideDbg(t *testing.T) {
 		require.Equal(t, 7, dbg.Exec3Workers)
 	})
 
+	t.Run("serial=true clamps Exec3Workers to 1", func(t *testing.T) {
+		dbg.SetExec3Workers(8)
+		run("--exec.serial=true")
+		require.Equal(t, 1, dbg.Exec3Workers)
+	})
+
+	t.Run("serial=true wins over --exec.workers", func(t *testing.T) {
+		dbg.SetExec3Workers(1)
+		// flags are applied in declaration order (workers first, then serial),
+		// so serial should override workers regardless of CLI argument order.
+		run("--exec.workers=12", "--exec.serial=true")
+		require.Equal(t, 1, dbg.Exec3Workers)
+	})
+
+	t.Run("serial=false leaves Exec3Workers untouched", func(t *testing.T) {
+		dbg.SetExec3Workers(8)
+		run("--exec.serial=false")
+		require.Equal(t, 8, dbg.Exec3Workers)
+	})
+
 	t.Run("no-merge and no-prune set to true", func(t *testing.T) {
 		dbg.SetNoMerge(false)
 		dbg.SetNoPrune(false)

node/cli/default_flags.go

@@ -50,6 +50,7 @@ var DefaultFlags = []cli.Flag{
 	&utils.ExecBatchedIOFlag,
 	&utils.ExecStateCacheFlag,
 	&utils.ExecWorkersFlag,
+	&utils.ExecSerialFlag,
 	&utils.ExecNoMergeFlag,
 	&utils.ExecNoPruneFlag,
 	&BatchSizeFlag,