feat (query/v2): Query Builder

.gitignore

@@ -7,5 +7,8 @@
 # Local integration test datasets
 integration/testdata/local/
 
+# Local benchmark comparison output
+.bench/
+
 # Local test and metric artifacts
 .coverage/

Makefile

@@ -3,6 +3,12 @@ THIS_FILE := $(lastword $(MAKEFILE_LIST))
 # Go configuration
 GO_CMD ?= go
 CGO_ENABLED ?= 0
+BENCH ?= .
+BENCH_COUNT ?= 10
+BENCH_TIME ?= 1s
+BENCH_BASE ?= main
+BENCH_TARGET ?= HEAD
+BENCH_KIND ?= all
 
 # Main packages to test/build
 MAIN_PACKAGES := $(shell $(GO_CMD) list ./...)
@@ -92,6 +98,14 @@ test_integration:
 	@echo "Running all integration tests..."
 	@$(GO_CMD) test -tags 'manual_integration integration' -race -cover -count=1 -p=1 -parallel=1 $(MAIN_PACKAGES)
 
+test_bench:
+	@echo "Running benchmarks..."
+	@$(GO_CMD) test -run '^$$' -bench '$(BENCH)' -benchmem -count=$(BENCH_COUNT) -benchtime=$(BENCH_TIME) $(MAIN_PACKAGES)
+
+bench_diff:
+	@echo "Running benchmark diff..."
+	@$(GO_CMD) run ./cmd/benchdiff --base '$(BENCH_BASE)' --target '$(BENCH_TARGET)' --kind '$(BENCH_KIND)' --bench '$(BENCH)' --bench-count '$(BENCH_COUNT)' --benchtime '$(BENCH_TIME)' $(BENCHDIFF_ARGS)
+
 test_neo4j:
 	@echo "Running Neo4j integration tests..."
 	@$(GO_CMD) test -tags integration -race -cover -count=1 -p=1 -parallel=1 $(MAIN_PACKAGES)
@@ -216,6 +230,7 @@ help:
 	@echo "  test_all    - Run all tests including integration tests"
 	@echo "  test_integration - Run all integration tests"
 	@echo "  test_bench  - Run benchmark test"
+	@echo "  bench_diff  - Compare benchmarks between commits"
 	@echo "  test_neo4j  - Run Neo4j integration tests"
 	@echo "  test_pg     - Run PostgreSQL integration tests"
 	@echo "  test_update - Update test cases"

README.md

@@ -56,6 +56,35 @@ export CONNECTION_STRING="neo4j://neo4j:weneedbetterpasswords@localhost:7687"
 
 Use `make test` for unit tests only and `make test_integration` for integration tests only.
 
+### Benchmarking
+
+Run the package benchmark suite with:
+
+```bash
+make test_bench
+```
+
+Use `cmd/benchdiff` to compare benchmarks between two committed refs without changing the active worktree:
+
+```bash
+go run ./cmd/benchdiff -base main -target HEAD -kind unit
+```
+
+For integration benchmark comparisons, provide the same `CONNECTION_STRING` used by integration tests:
+
+```bash
+export CONNECTION_STRING="postgresql://dawgs:weneedbetterpasswords@localhost:65432/dawgs"
+go run ./cmd/benchdiff -base main -target HEAD -kind all -driver pg -fail-regression 10%
+```
+
+The harness writes raw outputs and a Markdown report under `.bench/runs/` by default. The report begins with comparison
+findings, includes the raw `benchstat` output for each benchmark suite, and ends with a table of all captured benchmark
+numbers.
+
+The integration benchmark runner includes committed `base` and `traversal_shapes` datasets by default. The traversal
+shape suite checks expected result counts for chain, fanout, bounded cycle, disconnected, edge-kind-selective, and
+multi-path shortest-path scenarios before recording timings.
+
 ### Test Metrics
 
 `make test` writes unit test coverage artifacts under `.coverage/`:

cmd/benchdiff/README.md

@@ -0,0 +1,52 @@
+# Benchdiff
+
+Compares the existing benchmark suites between two committed git refs without changing the active worktree.
+
+## Usage
+
+```bash
+# Unit Go benchmarks only
+go run ./cmd/benchdiff -base main -target HEAD -kind unit
+
+# Unit and integration benchmarks
+export CONNECTION_STRING="postgresql://dawgs:weneedbetterpasswords@localhost:65432/dawgs"
+go run ./cmd/benchdiff -base main -target HEAD -kind all -driver pg
+
+# Fail if a benchmark median regresses by more than 10%
+go run ./cmd/benchdiff -base main -target HEAD -kind unit -fail-regression 10%
+```
+
+`benchdiff` creates detached worktrees under `.bench/`, runs each selected benchmark suite, writes raw output, and
+produces a Markdown report. The report starts with comparison findings, including median regressions, improvements,
+unchanged counts, and benchmark names that only appeared in one ref. It ends with an `All Executed Benchmark Numbers`
+section that lists the median, percent change, and sample counts for every benchmark captured in either ref. Worktrees
+are removed by default after the run; pass `-keep-worktrees` to preserve them.
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-base` | `main` | Base git ref |
+| `-target` | `HEAD` | Target git ref |
+| `-kind` | `all` | Benchmark kind (`all`, `unit`, `integration`) |
+| `-packages` | `./...` | Package list for Go benchmarks |
+| `-bench` | `.` | Go benchmark regexp |
+| `-bench-count` | `10` | Go benchmark repetition count |
+| `-benchtime` | `1s` | Go benchmark benchtime |
+| `-driver` | `pg` | Integration benchmark database driver |
+| `-connection` | | Integration connection string (or `CONNECTION_STRING`) |
+| `-dataset` | | Run only this integration dataset |
+| `-local-dataset` | | Add a local integration dataset |
+| `-dataset-dir` | `integration/testdata` | Integration testdata directory |
+| `-integration-iterations` | `10` | Timed iterations per integration scenario |
+| `-out` | `.bench/runs/<base>..<target>-<timestamp>` | Output directory |
+| `-benchstat` | `auto` | `benchstat` command, `auto`, or `none` |
+| `-fail-regression` | `0` | Median regression percentage that fails the command |
+| `-keep-worktrees` | `false` | Preserve temporary worktrees |
+
+If `benchstat` is not on `PATH` and `-benchstat auto` is used, the harness falls back to
+`go run golang.org/x/perf/cmd/benchstat@latest`.
+
+Integration comparisons use native `cmd/benchmark -format benchfmt` when both refs support it. If either ref predates
+that flag, the harness runs both refs in Markdown compatibility mode and compares each scenario's median as a single
+`ns/op` sample.