feat(go): add Go package with wazero WASM runtime, instance pool, and optimized parsing

[aepfli]

Summary

• Add pure Go package (go/) for evaluating feature flags using the flagd-evaluator WASM module
• Uses wazero for zero-CGO WebAssembly execution — no native dependencies
• Implements all 3 host-side optimizations matching the Java implementation:
  • Pre-evaluation cache: static/disabled flags served lock-free via atomic pointer (~22 ns, 0 allocs)
  • Context key filtering: only serialize keys referenced by targeting rules
  • Index-based evaluation: evaluate_by_index for O(1) flag lookup, avoiding string serialization
• WASM instance pool: N instances (default runtime.NumCPU()) for parallel targeting evaluation
• Hand-rolled JSON parser: avoids json.Unmarshal reflection overhead (5-7x faster)
• Generation guard: prevents stale flag index race between UpdateState and concurrent evaluations

Architecture

EvaluateFlag("key", ctx):
  1. atomic cache.Load()           → lock-free
  2. check pre-eval cache          → return if hit (no WASM, no lock)
  3. serialize context             → before acquiring instance
  4. inst = <-pool                 → blocks only if all instances busy
  5. generation check              → reload cache if UpdateState raced
  6. WASM evaluate on instance     → parallel across pool
  7. pool <- inst                  → return instance

Per-Evaluation Latency (single goroutine)

Scenario	WASM (this)	Native Go jsonlogic	Delta
Static flag (pre-eval cache)	22 ns / 0 allocs	1,280 ns / 12 allocs	58x faster
Targeting, small ctx (5 attrs)	5.4 µs / 11 allocs	4.3 µs / 62 allocs	0.8x
Targeting, large ctx (1000+ attrs)	6.1 µs / 11 allocs	291 µs / 3,022 allocs	48x faster

Throughput Scaling (1000 evals across N goroutines)

Targeting, small context:

Goroutines	WASM (pool)	Native jsonlogic	Winner
1	5.4 ms	4.3 ms	Native 1.3x
4	2.0 ms	2.4 ms	WASM 1.2x
16	1.6 ms	3.0 ms	WASM 1.9x

Targeting, large context (1000+ attrs):

Goroutines	WASM (pool)	Native jsonlogic	Winner
1	6.1 ms	291 ms	WASM 48x
4	2.3 ms	217 ms	WASM 94x
16	1.8 ms	203 ms	WASM 113x

Mixed workload (static + targeting + disabled):

Goroutines	Before (mutex)	After (pool)	Speedup
1	1.9 ms	2.1 ms	baseline
4	1.9 ms	0.86 ms	2.2x
16	2.0 ms	0.74 ms	2.7x

JSON Result Parsing (hand-rolled vs json.Unmarshal)

Result type	json.Unmarshal	Hand-rolled	Speedup
Bool	809 ns / 7 allocs	112 ns / 3 allocs	7.2x
String	838 ns / 9 allocs	144 ns / 5 allocs	5.8x
Number	950 ns / 9 allocs	160 ns / 4 allocs	5.9x
Error	883 ns / 8 allocs	138 ns / 4 allocs	6.4x
With metadata	1,843 ns / 20 allocs	399 ns / 11 allocs	4.6x

Files

File	Purpose
wasm.go	//go:embed, memory helpers
host.go	9 wazero host functions (3 modules)
types.go	EvaluationResult, UpdateStateResult, options (WithPoolSize, WithPermissiveValidation)
evaluator.go	Instance pool, UpdateState with parallel instance sync, generation stamping
evaluate.go	Lock-free evaluation pipeline, filtered context serialization
parse.go	Hand-rolled JSON parser for EvaluationResult (no json.Unmarshal on hot path)
evaluator_test.go	17 integration tests including TestGenerationGuard race test
benchmark_test.go	Full matrix (E1-E11, O1-O6, S1-S5, C1-C6) + throughput (T1-T9)
comparison_test.go	Build-tagged comparison vs diegoholiveira/jsonlogic/v3
fast_parse_test.go	Parser correctness and benchmark tests

Test plan

• All 17 integration tests pass (go test -v -race)
• Generation guard race test passes under -race detector (5 runs)
• All benchmarks compile and run (go test -bench=. -benchmem)
• Comparison benchmarks with build tag (go test -tags comparison -bench=.)
• Concurrent access test with 20 goroutines
• go build ./... clean
• Verify WASM binary matches release build

🤖 Generated with Claude Code