Cysql bench optimizer

.github/workflows/go-test.yml

@@ -51,6 +51,11 @@ jobs:
         run: |
           make test
 
+      - name: Verify Generated Test Cases
+        run: |
+          make test_update
+          git diff --exit-code
+
       - name: Parse Coverage Value From Feature Branch
         run: |
           echo "current_coverage=$(tail -n 1 .coverage/coverage.txt | awk '{print $3}' | awk 'sub("%", "")')" >> $GITHUB_ENV
@@ -115,6 +120,8 @@ jobs:
       - name: Run integration tests
         env:
           CONNECTION_STRING: postgres://dawgs:weneedbetterpasswords@localhost:5432/dawgs?sslmode=disable
+          DAWGS_INTEGRATION_ALLOW_DESTRUCTIVE: "1"
+          DAWGS_INTEGRATION_DISPOSABLE_TARGETS: postgresql://localhost:5432/dawgs
         run: |
           make test_integration
 
@@ -148,5 +155,7 @@ jobs:
       - name: Run integration tests
         env:
           CONNECTION_STRING: neo4j://neo4j:weneedbetterpasswords@localhost:7687
+          DAWGS_INTEGRATION_ALLOW_DESTRUCTIVE: "1"
+          DAWGS_INTEGRATION_DISPOSABLE_TARGETS: neo4j://localhost:7687/<default>
         run: |
           make test_integration

.gitignore

@@ -13,3 +13,7 @@ integration/testdata/local/
 
 # Local benchmark comparison output
 .bench/
+
+# Local performance captures and live-run artifacts
+/artifacts/perf/
+/artifacts/live/

AGENTS.md

@@ -16,6 +16,7 @@ These instructions apply to the entire repository.
 - Always format after code edits. Use `make format` unless a narrower formatting command is clearly sufficient for the touched files.
 - `make test_all` is the default validation command. It runs unit tests and all integration suites.
 - Integration suites consume `CONNECTION_STRING`. If `CONNECTION_STRING` is not present in the LLM context, ask the user to add it before running `make test_all`.
+- Destructive integration suites also require `DAWGS_INTEGRATION_ALLOW_DESTRUCTIVE=1` and an exact credential-free target in `DAWGS_INTEGRATION_DISPOSABLE_TARGETS`. Never add the live benchmark database to that allowlist.
 - Run `make test_all` only for the backend selected by the scheme in `CONNECTION_STRING`. Tests for other backends should skip themselves.
 - Core integration cases in `integration/testdata/cases` and `integration/testdata/templates` must be backend-equivalent. Do not add driver-specific skips or driver-specific expected assertions to these suites. If a backend capability needs dedicated coverage, put it in a clearly driver-scoped test that is skipped unless `CONNECTION_STRING` selects that backend.
 - `make test` is available for unit tests only.

GOLANG_CODING_STANDARD.md

@@ -10,11 +10,13 @@ type. The goal is to remove per-type receiver-name churn and reduce cognitive
 load while reading method bodies.
 
 ```go
+// Start begins serving requests.
 func (s *Server) Start() error {
 	go s.loop()
 	return nil
 }
 
+// Validate reports whether the configuration is supported.
 func (s Config) Validate() error {
 	if s.Firewall.Backend != "nftables" {
 		return fmt.Errorf("unsupported firewall backend %q", s.Firewall.Backend)
@@ -243,6 +245,29 @@ case <-s.joiner.StopC:
 Avoid splitting tightly coupled statements when the second line is the immediate
 effect of the first.
 
+## Documentation Comments
+
+Every function and method declaration and every struct or interface definition
+must have a semantically relevant Go doc comment, whether it is exported or
+unexported. Document every struct field and interface member individually,
+including embedded fields and embedded interface elements. Follow Go doc form
+by starting each comment with the declared identifier when applicable.
+
+Comments must explain the declaration's purpose, meaning, behavior, or contract.
+Merely restating the identifier without adding useful information does not
+satisfy this requirement.
+
+```go
+// RecordStore retrieves and persists records.
+type RecordStore interface {
+	// Find returns the record identified by key.
+	Find(ctx context.Context, key string) (Record, error)
+
+	// Save persists record and returns any write failure.
+	Save(ctx context.Context, record Record) error
+}
+```
+
 ## Function Ordering
 
 Prefer ordering functions in the same file so dependencies appear before the
@@ -256,12 +281,22 @@ Write struct type definitions across multiple lines, with one field per line.
 Align naturally with `gofmt`; do not compress structs onto one line.
 
 ```go
+// FirewallConfig controls how the firewall backend manages bans.
 type FirewallConfig struct {
-	Backend           string `toml:"backend"`
-	Table             string `toml:"table"`
-	BanSet            string `toml:"ban_set"`
-	Family            string `toml:"family"`
-	DryRunSummaryOnly bool   `toml:"dry_run_summary_only"`
+	// Backend selects the firewall implementation.
+	Backend string `toml:"backend"`
+
+	// Table identifies the firewall table managed by the backend.
+	Table string `toml:"table"`
+
+	// BanSet identifies the set containing banned addresses.
+	BanSet string `toml:"ban_set"`
+
+	// Family selects the address family managed by the backend.
+	Family string `toml:"family"`
+
+	// DryRunSummaryOnly limits dry-run output to a summary.
+	DryRunSummaryOnly bool `toml:"dry_run_summary_only"`
 }
 ```
 
@@ -320,13 +355,41 @@ defer fin.Close()
 ```
 
 Use package-level grouped `const` and `var` declarations for related values.
+Every package-level (global) `var` and `const` entity must have a semantically
+relevant Go doc comment, whether it is exported or unexported. Document each
+member of a grouped declaration individually. Comments on function-local `var`
+declarations are optional and left to the author's discretion.
 
 ```go
+// ErrNotFound indicates that the requested record does not exist.
+var ErrNotFound = errors.New("not found")
+
 const (
-	ErrNotFound = errors.New("not found")
+	// fileWatchKey formats a file watch key.
+	fileWatchKey KeyFormat = "file_watch.%s"
+
+	// hostRecordKey formats a host record key.
+	hostRecordKey KeyFormat = "hosts.%s"
 
-	fileWatchKey        KeyFormat = "file_watch.%s"
-	hostRecordKey       KeyFormat = "hosts.%s"
+	// hostRecordKeyPrefix identifies the host record key namespace.
 	hostRecordKeyPrefix KeyFormat = "hosts."
 )
 ```
+
+In grouped `var` and `const` declarations, treat each leading comment and the
+member definition it documents as one unit. Separate that unit from the next
+comment and member definition with exactly one blank line. The final member
+definition may instead be followed directly by the closing `)`.
+
+```go
+var (
+	// expansionRootFilter identifies the recursive traversal root filter.
+	expansionRootFilter = pgsql.Identifier("traversal_root_filter")
+
+	// expansionTerminalFilter identifies the recursive traversal terminal filter.
+	expansionTerminalFilter = pgsql.Identifier("traversal_terminal_filter")
+
+	// expansionPairFilter identifies the recursive traversal pair filter.
+	expansionPairFilter = pgsql.Identifier("traversal_pair_filter")
+)
+```

Makefile

@@ -2,6 +2,7 @@ THIS_FILE := $(lastword $(MAKEFILE_LIST))
 
 # Go configuration
 GO_CMD ?= go
+GOIMPORTS_CMD ?= goimports
 CGO_ENABLED ?= 0
 BENCH ?= .
 BENCH_COUNT ?= 10
@@ -33,6 +34,37 @@ METRICS_ENFORCE ?= 0
 BENCHMARK_REPORT ?=
 BENCHMARK_BASELINE ?=
 BENCHMARK_REGRESSION ?= 0.20
+PERF_BASELINE ?=
+PERF_CANDIDATE ?=
+PERF_GATE_OUTPUT ?= $(METRICS_DIR)/perf-gate.json
+PERF_GATE_SEED ?= 1
+PERF_CONFIDENCE ?= 0.975
+PERF_REGRESSION ?= 0.05
+# Promotion-grade gates must override this with one or more workload names
+# whose improvement is required to clear the host A/A-aware materiality floor.
+PERF_TARGETS ?=
+PERF_MATERIALITY_RATIO ?= 0.95
+PERF_MATERIALITY_ABSOLUTE ?= 100us
+PERF_AA_ARTIFACT ?=
+PERF_AA_OUTPUT ?= $(METRICS_DIR)/perf-aa-resolution.json
+PERF_GATE_AA ?= $(PERF_AA_OUTPUT)
+PERF_LEFT ?=
+PERF_RIGHT ?=
+PERF_CONFIRM_AA ?=
+PERF_CONFIRM_OUTPUT ?= $(METRICS_DIR)/perf-confirmation.json
+PERF_CASES ?=
+PERF_FILTER_CASES ?=
+PERF_DIAGNOSTIC_GATE ?= 0
+PERF_BUNDLE_VERIFY_DIR ?=
+PERF_BUNDLE_VERIFY_OUTPUT ?= $(METRICS_DIR)/capture-bundle-verification.json
+PERF_BUNDLE_REQUIRE_CLEAN ?= 0
+PERF_EXPAND_INTO_ARTIFACT ?=
+PERF_EXPAND_INTO_OUTPUT ?= $(METRICS_DIR)/expand-into-study.json
+PERF_EXPAND_INTO_PROTOCOL ?= discovery
+PERF_TOURNAMENT_ARTIFACT ?=
+PERF_TOURNAMENT_OUTPUT ?= $(METRICS_DIR)/reference-tournament.json
+PERF_TOURNAMENT_ARMS ?=
+PERF_TOURNAMENT_PROTOCOL ?= confirmation
 FUZZ_REPORT ?=
 MUTATION_REPORT ?=
 BACKEND_RESULT_ARGS ?=
@@ -56,7 +88,7 @@ QUALITY_INPUTS += -mutation-report $(MUTATION_REPORT)
 endif
 QUALITY_INPUTS += -benchmark-regression $(BENCHMARK_REGRESSION)
 
-.PHONY: default all build deps tidy lint format test test_all test_integration test_neo4j test_pg test_update plan_corpus complexity complexity_check crap crap_check quality quality_check quality_backend quality_bench metrics metrics_check generate clean help
+.PHONY: default all build deps tidy lint format test test_all test_integration test_neo4j test_pg test_update plan_corpus perf_gate perf_aa perf_confirm perf_bundle_verify perf_expand_into perf_tournament complexity complexity_check crap crap_check quality quality_check quality_backend quality_bench metrics metrics_check generate clean help
 
 # Default target
 default: help
@@ -79,11 +111,12 @@ tidy:
 # Code quality
 lint:
 	@echo "Running linter..."
-	@$(GO_CMD) vet ./...
+	@$(GO_CMD) vet -unreachable=false ./...
+	@$(GO_CMD) list ./... | grep -v '/cypher/parser$$' | xargs $(GO_CMD) vet -unreachable
 
 format:
 	@echo "Formatting code..."
-	@find ./ -name '*.go' -print0 | xargs -P 12 -0 -I '{}' goimports -w '{}'
+	@find ./ \( -path './.git' -o -path './.coverage' \) -prune -o -name '*.go' -print0 | xargs -P 12 -0 -I '{}' $(GOIMPORTS_CMD) -w '{}'
 
 # Test targets
 test: $(METRICS_DIR)
@@ -96,6 +129,7 @@ test_all: test test_integration
 
 test_integration:
 	@echo "Running all integration tests..."
+	@$(GO_CMD) run ./cmd/integrationguard
 	@$(GO_CMD) test -tags 'manual_integration integration' -race -cover -count=1 -p=1 -parallel=1 $(MAIN_PACKAGES)
 
 test_bench:
@@ -108,10 +142,12 @@ bench_diff:
 
 test_neo4j:
 	@echo "Running Neo4j integration tests..."
+	@$(GO_CMD) run ./cmd/integrationguard
 	@$(GO_CMD) test -tags integration -race -cover -count=1 -p=1 -parallel=1 $(MAIN_PACKAGES)
 
 test_pg:
 	@echo "Running PostgreSQL integration tests..."
+	@$(GO_CMD) run ./cmd/integrationguard
 	@$(GO_CMD) test -tags manual_integration -race -cover -count=1 -p=1 -parallel=1 $(MAIN_PACKAGES)
 
 test_update:
@@ -127,6 +163,93 @@ plan_corpus: $(METRICS_DIR)
 	@echo "Capturing Cypher plan corpus..."
 	@$(GO_CMD) run ./cmd/plancorpus
 
+perf_gate: $(METRICS_DIR)
+	@if [ -z "$(PERF_BASELINE)" ] || [ -z "$(PERF_CANDIDATE)" ]; then \
+		echo "PERF_BASELINE and PERF_CANDIDATE are required."; \
+		exit 1; \
+	fi
+	@if [ "$(PERF_DIAGNOSTIC_GATE)" != "1" ] && [ -z "$(strip $(PERF_TARGETS))" ]; then \
+		echo "PERF_TARGETS is required for a promotion-grade performance gate."; \
+		exit 1; \
+	fi
+	@$(GO_CMD) run ./cmd/graphbench \
+		-gate-baseline "$(PERF_BASELINE)" \
+		-gate-candidate "$(PERF_CANDIDATE)" \
+		-gate-output "$(PERF_GATE_OUTPUT)" \
+		-gate-aa "$(PERF_GATE_AA)" \
+		-seed "$(PERF_GATE_SEED)" \
+		-confidence-level "$(PERF_CONFIDENCE)" \
+		-regression-threshold "$(PERF_REGRESSION)" \
+		-gate-targets "$(PERF_TARGETS)" \
+		-materiality-ratio "$(PERF_MATERIALITY_RATIO)" \
+		-materiality-absolute "$(PERF_MATERIALITY_ABSOLUTE)" \
+		-cases "$(PERF_FILTER_CASES)" \
+		-diagnostic-gate="$(PERF_DIAGNOSTIC_GATE)"
+
+perf_aa: $(METRICS_DIR)
+	@if [ -z "$(PERF_AA_ARTIFACT)" ]; then \
+		echo "PERF_AA_ARTIFACT is required."; \
+		exit 1; \
+	fi
+	@$(GO_CMD) run ./cmd/graphbench \
+		-aa-artifact "$(PERF_AA_ARTIFACT)" \
+		-aa-output "$(PERF_AA_OUTPUT)" \
+		-seed "$(PERF_GATE_SEED)" \
+		-confidence-level "$(PERF_CONFIDENCE)"
+
+perf_confirm: $(METRICS_DIR)
+	@if [ -z "$(PERF_LEFT)" ] || [ -z "$(PERF_RIGHT)" ]; then \
+		echo "PERF_LEFT and PERF_RIGHT are required."; \
+		exit 1; \
+	fi
+	@$(GO_CMD) run ./cmd/graphbench \
+		-confirm-left "$(PERF_LEFT)" \
+		-confirm-right "$(PERF_RIGHT)" \
+		-confirm-aa "$(PERF_CONFIRM_AA)" \
+		-confirm-output "$(PERF_CONFIRM_OUTPUT)" \
+		-confirm-cases "$(PERF_CASES)" \
+		-seed "$(PERF_GATE_SEED)" \
+		-confidence-level "$(PERF_CONFIDENCE)"
+
+perf_bundle_verify: $(METRICS_DIR)
+	@if [ -z "$(PERF_BUNDLE_VERIFY_DIR)" ]; then \
+		echo "PERF_BUNDLE_VERIFY_DIR is required."; \
+		exit 1; \
+	fi
+	@$(GO_CMD) run ./cmd/graphbench \
+		-bundle-verify "$(PERF_BUNDLE_VERIFY_DIR)" \
+		-bundle-verify-output "$(PERF_BUNDLE_VERIFY_OUTPUT)" \
+		-bundle-require-clean="$(PERF_BUNDLE_REQUIRE_CLEAN)"
+
+perf_expand_into: $(METRICS_DIR)
+	@if [ -z "$(PERF_EXPAND_INTO_ARTIFACT)" ]; then \
+		echo "PERF_EXPAND_INTO_ARTIFACT is required."; \
+		exit 1; \
+	fi
+	@$(GO_CMD) run ./cmd/graphbench \
+		-expand-into-artifact "$(PERF_EXPAND_INTO_ARTIFACT)" \
+		-expand-into-output "$(PERF_EXPAND_INTO_OUTPUT)" \
+		-expand-into-protocol "$(PERF_EXPAND_INTO_PROTOCOL)" \
+		-seed "$(PERF_GATE_SEED)" \
+		-confidence-level "$(PERF_CONFIDENCE)" \
+		-materiality-ratio "$(PERF_MATERIALITY_RATIO)" \
+		-materiality-absolute "$(PERF_MATERIALITY_ABSOLUTE)"
+
+perf_tournament: $(METRICS_DIR)
+	@if [ -z "$(PERF_TOURNAMENT_ARTIFACT)" ] || [ -z "$(PERF_TOURNAMENT_ARMS)" ]; then \
+		echo "PERF_TOURNAMENT_ARTIFACT and PERF_TOURNAMENT_ARMS are required."; \
+		exit 1; \
+	fi
+	@$(GO_CMD) run ./cmd/graphbench \
+		-reference-tournament-artifact "$(PERF_TOURNAMENT_ARTIFACT)" \
+		-reference-tournament-output "$(PERF_TOURNAMENT_OUTPUT)" \
+		-reference-tournament-arms "$(PERF_TOURNAMENT_ARMS)" \
+		-reference-tournament-protocol "$(PERF_TOURNAMENT_PROTOCOL)" \
+		-seed "$(PERF_GATE_SEED)" \
+		-confidence-level "$(PERF_CONFIDENCE)" \
+		-materiality-ratio "$(PERF_MATERIALITY_RATIO)" \
+		-materiality-absolute "$(PERF_MATERIALITY_ABSOLUTE)"
+
 # Metric targets
 $(METRICS_DIR):
 	@mkdir -p $(METRICS_DIR)
@@ -179,6 +302,8 @@ quality_backend: test
 		echo "PG_CONNECTION_STRING and NEO4J_CONNECTION_STRING are required."; \
 		exit 1; \
 	fi
+	@CONNECTION_STRING="$(PG_CONNECTION_STRING)" $(GO_CMD) run ./cmd/integrationguard
+	@CONNECTION_STRING="$(NEO4J_CONNECTION_STRING)" $(GO_CMD) run ./cmd/integrationguard
 	@set +e; \
 	CONNECTION_STRING="$(PG_CONNECTION_STRING)" $(GO_CMD) test -json -tags 'manual_integration integration' -race -cover -count=1 -p=1 -parallel=1 $(MAIN_PACKAGES) > $(BACKEND_PG_REPORT); \
 	pg_status=$$?; \
@@ -238,6 +363,12 @@ help:
 	@echo "  test_neo4j  - Run Neo4j integration tests"
 	@echo "  test_pg     - Run PostgreSQL integration tests"
 	@echo "  plan_corpus - Capture shared corpus query plans for configured backends"
+	@echo "  perf_gate   - Compare complete declared GraphBench artifacts"
+	@echo "  perf_aa     - Calculate A/A measurement resolution for GraphBench"
+	@echo "  perf_confirm - Build a paired GraphBench confirmation report"
+	@echo "  perf_bundle_verify - Verify a portable GraphBench capture bundle"
+	@echo "  perf_expand_into - Build the fixed-one-hop three-arm study report"
+	@echo "  perf_tournament - Qualify a predeclared three- or five-arm reference tournament"
 	@echo "  test_update - Update test cases"
 	@echo "  complexity  - Report cyclomatic complexity"
 	@echo "  crap        - Report CRAP scores from unit test coverage"