benchmarks: add routing complex baseline and observability surface

[emil14]

No description provided.

[github-actions]

PR Review: benchmarks: add routing complex baseline and observability surface

Summary

This PR establishes a comprehensive runtime benchmarking infrastructure for Neva, adding:

• CI workflow for automated benchmark execution on PR/push/release
• 4 new benchmark programs covering simple and complex routing scenarios
• Documentation for contributors and benchmark taxonomy
• Make targets for local development iteration

Detailed Review

1. .github/workflows/runtime-benchmarks.yml ⭐

Strengths:

• Uses modern action versions (checkout@v5, setup-go@v6)
• Proper 30-minute timeout to prevent runaway jobs
• Artifact-based approach with clear documentation that runner deltas shouldn't be merge gates
• Comprehensive metadata capture (event type, SHA, Go version, etc.)
• Explicit artifact naming with commit SHA for traceability

Suggestions: None - this is well-designed.

2. Makefile additions

The two new targets are practical:

• bench-runtime: Full suite for CI/comparison
• bench-runtime-routing-complex: Targeted slice for iteration (references Add runtime benchmark baseline before Msg redesign #1023)

The regex pattern '^BenchmarkRuntimeE2E/(simple_routers_basic|simple_selectors_basic|complex_)' correctly captures the new benchmarks plus all complex ones.

3. Benchmark Programs

benchmarks/simple/routers/basic/main.neva

• Tests Cond, Switch, Race, and If router components
• Clean composition with Mod/Eq for conditional logic
• 10,000 iterations via streams.Range

benchmarks/simple/selectors/basic/main.neva

• Tests Ternary, Match, and Select selector components
• Good coverage of selector patterns with constants
• 10,000 iterations

benchmarks/complex/control_flow/selectors_routers/main.neva

• Comprehensive mix of both selectors and routers
• Includes union boxing/unboxing (Union, Switch)
• Proper error handling with runtime.Panic for unexpected paths
• Tests the full control-flow surface

benchmarks/complex/types/struct_union_combo/main.neva

• Tests composite data paths with struct + union interaction
• Uses Struct builder and field selectors (.boxed)
• 100,000 iterations (higher volume for data-path testing)

All benchmarks:

• ✅ Follow AGENTS.md naming conventions (scenario-based, not implementation buckets)
• ✅ Have deterministic termination via streams.Wait
• ✅ Are appropriately scoped per tier definitions
• ✅ Use minimal support wiring with clear data flow

4. benchmarks/bench_test.go

Excellent harness design:

• Builds CLI once, reuses for all benchmarks
• Uses testing.B.Loop() (modern Go approach)
• Isolated temp modules per benchmark package
• 30-second timeout for individual runs
• Proper artifact preparation via e2e helpers

5. Documentation Updates

benchmarks/AGENTS.md

• Updates taxonomy guidance (removes old operator/type trees)
• Prefers benchmarks/<tier>/<pkg>/main.neva structure
• Good guidance on when to use scoped prefixes

benchmarks/README.md

• Clear explanation of tier structure
• Documents benchstat workflow
• Notes that allocs/op is intentionally not reported (external binary)

CONTRIBUTING.md

• Practical section on running benchmarks locally
• References CI workflow and make targets

docs/README.md

• Adds link to runtime benchmarks documentation

Issues Found

None. This is a well-structured PR that follows existing conventions and adds meaningful observability.

Recommendations

Approved. The PR:

1. ✅ Adds valuable benchmark coverage for routing and complex scenarios
2. ✅ Establishes proper CI artifact workflow for performance tracking
3. ✅ Follows AGENTS.md taxonomy and naming conventions
4. ✅ Includes comprehensive documentation
5. ✅ Uses modern Go testing patterns (b.Loop)
6. ✅ Correctly notes that GitHub-hosted runners shouldn't gate merges

The benchmarks are appropriately scoped (simple vs complex tiers), have deterministic termination, and test meaningful runtime paths. The artifact-only approach is the right call for CI benchmarking given runner variability.

---

Status: MERGED (as noted in PR context) - the review confirms this was a solid addition to the project's observability infrastructure.

opencode session  |  github run