perf: cut per-fire and per-verify allocations in the state engine

matchingTransitions returns the specific or wildcard slice directly when
only one kind is present, so the steady-state bubble path no longer
allocates a merged slice. activeParallelAncestor presizes its scratch map
from the leaf count, and runActions builds the formatted effect label and
probes the comm microstep only in full trace mode, keeping the lite hot
path free of the Sprintf and effectLabel allocation.

Verify rounds the machine through its public IR once and threads it into
the topology, search-graph, and config-graph builders instead of
re-serializing per builder. The config graph caches its inverted child
index at build time so leavesUnder no longer rebuilds and re-sorts it on
every call. A new CompileChecked binds a stored rich AST to its
environment once for reuse across evaluations, with EvalCheckedAST now a
one-shot wrapper over it.

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>

Author: joshua-temple

state/expr/coverage_test.go

@@ -45,6 +45,61 @@ func TestEvalCheckedAST_RejectsBadBytes(t *testing.T) {
 	}
 }
 
+// TestCompileChecked_ReusesProgramAcrossEvals asserts a CompiledChecked built once
+// evaluates many context values and agrees with the one-shot EvalCheckedAST on each,
+// proving the cached program path is equivalent to the rebuild-every-call path.
+func TestCompileChecked_ReusesProgramAcrossEvals(t *testing.T) {
+	reg := state.NewRegistry[order]()
+	cat := expr.NewCatalog()
+	if _, err := expr.Guard[string](reg, "big", `total > 100.0`, orderSchema(), expr.WithCatalog(cat)); err != nil {
+		t.Fatalf("Guard: %v", err)
+	}
+	entry, ok := cat.Entry("big")
+	if !ok {
+		t.Fatal("catalog recorded no entry")
+	}
+
+	compiled, err := expr.CompileChecked(entry.CheckedAST, orderSchema())
+	if err != nil {
+		t.Fatalf("CompileChecked: %v", err)
+	}
+
+	for _, tc := range []struct {
+		total float64
+		want  bool
+	}{
+		{total: 50, want: false},
+		{total: 150, want: true},
+		{total: 100, want: false},
+		{total: 101, want: true},
+	} {
+		entity := order{Total: tc.total}
+		got, err := compiled.Eval(entity)
+		if err != nil {
+			t.Fatalf("Eval(total=%v): %v", tc.total, err)
+		}
+		if got != tc.want {
+			t.Fatalf("Eval(total=%v) = %v, want %v", tc.total, got, tc.want)
+		}
+		// The reusable program agrees with the rebuild-every-call helper.
+		oneShot, err := expr.EvalCheckedAST(entry.CheckedAST, orderSchema(), entity)
+		if err != nil {
+			t.Fatalf("EvalCheckedAST(total=%v): %v", tc.total, err)
+		}
+		if oneShot != got {
+			t.Fatalf("CompiledChecked.Eval=%v disagrees with EvalCheckedAST=%v at total=%v", got, oneShot, tc.total)
+		}
+	}
+}
+
+// TestCompileChecked_RejectsBadBytes asserts malformed checked-AST bytes fail at
+// compile time rather than at evaluation.
+func TestCompileChecked_RejectsBadBytes(t *testing.T) {
+	if _, err := expr.CompileChecked([]byte{0xff, 0xfe, 0xfd}, orderSchema()); err == nil {
+		t.Fatal("malformed checked-AST bytes should fail to compile")
+	}
+}
+
 // TestLoadCatalog_RejectsMalformedSidecar asserts a sidecar that is not an object,
 // and one whose checked-AST is not valid base64, are both rejected.
 func TestLoadCatalog_RejectsMalformedSidecar(t *testing.T) {

state/expr/program.go

@@ -96,23 +96,55 @@ func checkedASTBytes(ast *cel.Ast) ([]byte, error) {
 // The AST is rebound against the schema-derived env so its variables resolve; an env
 // whose variables do not match the AST's declarations surfaces as an eval error.
 func EvalCheckedAST(checkedAST []byte, schema state.ContextSchema, entity any) (bool, error) {
-	ast, err := astFromCheckedBytes(checkedAST)
+	compiled, err := CompileChecked(checkedAST, schema)
 	if err != nil {
 		return false, err
 	}
+	return compiled.Eval(entity)
+}
+
+// CompiledChecked is a rich AST that has been rebuilt and bound to its
+// schema-derived environment exactly once, ready to evaluate against many context
+// values. EvalCheckedAST rebuilds the env and program on every call, which is fine
+// for a one-shot tooling probe but wasteful when the same stored AST is replayed
+// repeatedly; CompileChecked pays that cost once and Eval reuses the program. The
+// type is immutable after construction and its Eval is safe for the same
+// synchronous, single-evaluator use as a celGuard.
+type CompiledChecked struct {
+	program cel.Program
+	schema  state.ContextSchema
+}
+
+// CompileChecked rebuilds a program from stored canonical cel.dev/expr CheckedExpr
+// bytes and binds it to the schema-derived environment once, returning a reusable
+// CompiledChecked. It performs the same env-rebuild and program-build EvalCheckedAST
+// does, so a malformed AST or an env whose variables do not match the AST's
+// declarations surfaces here rather than per evaluation.
+func CompileChecked(checkedAST []byte, schema state.ContextSchema) (*CompiledChecked, error) {
+	ast, err := astFromCheckedBytes(checkedAST)
+	if err != nil {
+		return nil, err
+	}
 	env, err := newEnv(schema)
 	if err != nil {
-		return false, fmt.Errorf("rebuild env: %w", err)
+		return nil, fmt.Errorf("rebuild env: %w", err)
 	}
 	program, err := env.Program(ast, cel.CostLimit(defaultCostLimit))
 	if err != nil {
-		return false, fmt.Errorf("rebuild program: %w", err)
+		return nil, fmt.Errorf("rebuild program: %w", err)
 	}
-	activation, err := marshalActivation(entity, schema)
+	return &CompiledChecked{program: program, schema: schema}, nil
+}
+
+// Eval projects the entity into the bound environment and evaluates the compiled
+// program, returning its boolean verdict. It reuses the program built by
+// CompileChecked, so repeated evaluations skip the env/AST/program rebuild.
+func (c *CompiledChecked) Eval(entity any) (bool, error) {
+	activation, err := marshalActivation(entity, c.schema)
 	if err != nil {
 		return false, err
 	}
-	out, _, err := program.Eval(activation)
+	out, _, err := c.program.Eval(activation)
 	if err != nil {
 		return false, fmt.Errorf("eval: %w", err)
 	}

state/fire.go

@@ -422,6 +422,10 @@ func (i *Instance[S, E, C]) fireSpine(ctx context.Context, event E, tr Trace) Fi
 // events outrank the wildcard — and the wildcard outranks bubbling to an
 // ancestor.
 func matchingTransitions[S comparable, E comparable, C any](s *State[S, E, C], event E) []*Transition[S, E, C] {
+	// The overwhelmingly common case is a state with one or more specific matches
+	// and no wildcard. Collect specifics first; only allocate a second slice and
+	// merge when a wildcard is actually present, so the steady-state path returns a
+	// single slice with no merge allocation. A state with no matches returns nil.
 	var specific, wild []*Transition[S, E, C]
 	for ti := range s.Transitions {
 		t := &s.Transitions[ti]
@@ -435,7 +439,15 @@ func matchingTransitions[S comparable, E comparable, C any](s *State[S, E, C], e
 			specific = append(specific, t)
 		}
 	}
-	return append(specific, wild...)
+	if len(wild) == 0 {
+		return specific
+	}
+	if len(specific) == 0 {
+		return wild
+	}
+	out := make([]*Transition[S, E, C], 0, len(specific)+len(wild))
+	out = append(out, specific...)
+	return append(out, wild...)
 }
 
 // forbids reports whether state s explicitly forbids event: a transition marked
@@ -756,9 +768,15 @@ func (i *Instance[S, E, C]) runActions(refs []Ref, entity C, tr *Trace) (effects
 			return effects, a.Name, aerr
 		}
 		effects = append(effects, e)
-		tr.recordEffect(fmt.Sprintf("%s:%s", a.Name, effectLabel(e)))
-		if ms, ok := commMicrostep(e); ok {
-			tr.note(ms)
+		// recordEffect/note are no-ops in lite mode, so build the formatted effect
+		// label and probe the comm microstep only when the full trace will keep them.
+		// This keeps the default (lite) hot path free of the Sprintf and effectLabel
+		// allocation on every action.
+		if tr.full {
+			tr.recordEffect(fmt.Sprintf("%s:%s", a.Name, effectLabel(e)))
+			if ms, ok := commMicrostep(e); ok {
+				tr.note(ms)
+			}
 		}
 	}
 	return effects, "", nil

state/parallel.go

@@ -20,7 +20,11 @@ func (i *Instance[S, E, C]) activeParallelAncestor() (S, bool) {
 		return zero, false
 	}
 	// Candidate parallel states are the ancestors shared by the config leaves.
-	seen := map[S]int{}
+	// Presize from the leaf count so the map does not grow-and-rehash while the
+	// orthogonal config is scanned. This runs only when already in a parallel
+	// configuration (len(config) >= 2); flat machines return above without
+	// allocating.
+	seen := make(map[S]int, len(i.config))
 	for _, leaf := range i.config {
 		for _, anc := range m.ancestors(leaf) {
 			n, ok := m.resolveNode(anc)

state/verify/invariant.go

@@ -118,33 +118,64 @@ type configGraph struct {
 	// edges maps a source state to its path-advancing outgoing transitions in
 	// declaration order, so exploration is deterministic.
 	edges map[string][]searchEdge
+	// children inverts parent into a sorted child list per state, computed once at
+	// build time. leavesUnder walks it on the hot successors path, so caching it
+	// avoids rebuilding and re-sorting the whole index on every call.
+	children map[string][]string
 }
 
 // buildConfigGraph flattens the machine's public IR into a configGraph. A machine
 // whose IR cannot be read yields the zero graph (hasInitial false) rather than
 // panicking, matching Verify's no-panic contract.
 func buildConfigGraph[S comparable, E comparable, C any](m *state.Machine[S, E, C]) configGraph {
-	g := configGraph{
-		parent:          map[string]string{},
-		leaf:            map[string]bool{},
-		compoundInitial: map[string]string{},
-		regionInitials:  map[string][]string{},
-		edges:           map[string][]searchEdge{},
-	}
 	ir, ok := loadIR(m)
 	if !ok {
-		return g
+		return emptyConfigGraph()
 	}
+	return buildConfigGraphFromIR(ir)
+}
+
+// buildConfigGraphFromIR builds the configGraph from an already-loaded IR, so a
+// caller that round-tripped the machine once can reuse it.
+func buildConfigGraphFromIR[S comparable, E comparable, C any](ir *state.IR[S, E, C]) configGraph {
+	g := emptyConfigGraph()
 	if ir.HasInitial {
 		g.hasInitial = true
 		g.initial = fmt.Sprint(ir.Initial)
 	}
 	for i := range ir.States {
 		collectConfig(&ir.States[i], "", &g)
 	}
+	g.children = buildChildIndex(g.parent)
 	return g
 }
 
+// emptyConfigGraph returns a configGraph with initialized maps and no states.
+func emptyConfigGraph() configGraph {
+	return configGraph{
+		parent:          map[string]string{},
+		leaf:            map[string]bool{},
+		compoundInitial: map[string]string{},
+		regionInitials:  map[string][]string{},
+		edges:           map[string][]searchEdge{},
+	}
+}
+
+// buildChildIndex inverts the parent map into a sorted child list per state, so a
+// subtree walk is deterministic and does not range a map directly.
+func buildChildIndex(parent map[string]string) map[string][]string {
+	idx := map[string][]string{}
+	for name, p := range parent {
+		if p != "" {
+			idx[p] = append(idx[p], name)
+		}
+	}
+	for p := range idx {
+		sort.Strings(idx[p])
+	}
+	return idx
+}
+
 // collectConfig records one state's structure — parent, leaf-ness, compound and
 // region initial children, and path-advancing edges — and recurses through its
 // children and region states in declaration order.
@@ -348,15 +379,14 @@ func (g configGraph) successors(leaves []string) []configStep {
 // it is every descendant leaf, found by walking the parent relation (which covers
 // both compound children and region states).
 func (g configGraph) leavesUnder(node string) map[string]bool {
-	children := g.childIndex()
 	out := map[string]bool{}
 	var walk func(n string)
 	walk = func(n string) {
 		if g.leaf[n] {
 			out[n] = true
 			return
 		}
-		for _, c := range children[n] {
+		for _, c := range g.children[n] {
 			walk(c)
 		}
 	}
@@ -367,21 +397,6 @@ func (g configGraph) leavesUnder(node string) map[string]bool {
 	return out
 }
 
-// childIndex inverts the parent map into a sorted child list per state, so a
-// subtree walk is deterministic and does not range a map directly.
-func (g configGraph) childIndex() map[string][]string {
-	idx := map[string][]string{}
-	for name, p := range g.parent {
-		if p != "" {
-			idx[p] = append(idx[p], name)
-		}
-	}
-	for p := range idx {
-		sort.Strings(idx[p])
-	}
-	return idx
-}
-
 // invariantFor decides a single invariant over an already-built exploration,
 // returning the finding. The exploration is walked in breadth-first discovery
 // order so the reported counterexample is the nearest violating configuration,

state/verify/ir.go

@@ -25,11 +25,17 @@ type topology struct {
 // cannot be read yields the zero topology rather than panicking, matching
 // Verify's no-panic contract.
 func readTopology[S comparable, E comparable, C any](m *state.Machine[S, E, C]) topology {
-	t := topology{parent: map[string]string{}}
 	ir, ok := loadIR(m)
 	if !ok {
-		return t
+		return topology{parent: map[string]string{}}
 	}
+	return topologyFromIR(ir)
+}
+
+// topologyFromIR builds a topology from an already-loaded IR, so a caller that has
+// round-tripped the machine once can reuse it instead of re-serializing.
+func topologyFromIR[S comparable, E comparable, C any](ir *state.IR[S, E, C]) topology {
+	t := topology{parent: map[string]string{}}
 	for i := range ir.States {
 		collectStates(&ir.States[i], "", &t)
 	}
@@ -57,7 +63,15 @@ func collectStates[S comparable, E comparable, C any](s *state.State[S, E, C], p
 // declares no initial state.
 func initialName[S comparable, E comparable, C any](m *state.Machine[S, E, C]) string {
 	ir, ok := loadIR(m)
-	if !ok || !ir.HasInitial {
+	if !ok {
+		return ""
+	}
+	return initialNameFromIR(ir)
+}
+
+// initialNameFromIR returns the initial state name from an already-loaded IR.
+func initialNameFromIR[S comparable, E comparable, C any](ir *state.IR[S, E, C]) string {
+	if !ir.HasInitial {
 		return ""
 	}
 	return fmt.Sprint(ir.Initial)

state/verify/reach.go

@@ -65,16 +65,17 @@ type searchEdge struct {
 // whose IR cannot be read yields the zero graph (hasInitial false) rather than
 // panicking, matching Verify's no-panic contract.
 func buildSearchGraph[S comparable, E comparable, C any](m *state.Machine[S, E, C]) searchGraph {
-	g := searchGraph{
-		nodes:           map[string]bool{},
-		parent:          map[string]string{},
-		initialChildren: map[string][]string{},
-		edges:           map[string][]searchEdge{},
-	}
 	ir, ok := loadIR(m)
 	if !ok {
-		return g
+		return emptySearchGraph()
 	}
+	return buildSearchGraphFromIR(ir)
+}
+
+// buildSearchGraphFromIR builds the searchGraph from an already-loaded IR, so a
+// caller that round-tripped the machine once can reuse it.
+func buildSearchGraphFromIR[S comparable, E comparable, C any](ir *state.IR[S, E, C]) searchGraph {
+	g := emptySearchGraph()
 	if ir.HasInitial {
 		g.hasInitial = true
 		g.initial = fmt.Sprint(ir.Initial)
@@ -85,6 +86,16 @@ func buildSearchGraph[S comparable, E comparable, C any](m *state.Machine[S, E,
 	return g
 }
 
+// emptySearchGraph returns a searchGraph with initialized maps and no states.
+func emptySearchGraph() searchGraph {
+	return searchGraph{
+		nodes:           map[string]bool{},
+		parent:          map[string]string{},
+		initialChildren: map[string][]string{},
+		edges:           map[string][]searchEdge{},
+	}
+}
+
 // collectSearch records one state's structure — parent, initial-descent children,
 // and path-advancing edges — and recurses through its children and region states
 // in declaration order.