CySQL Query Optimizer Framework

Makefile

@@ -50,7 +50,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 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 complexity complexity_check crap crap_check quality quality_check quality_backend quality_bench metrics metrics_check generate clean help
 
 # Default target
 default: help
@@ -109,6 +109,10 @@ test_update:
 	@cp -fv cypher/models/pgsql/test/updated_cases/* cypher/models/pgsql/test/translation_cases
 	@rm -rf cypher/models/pgsql/test/updated_cases
 
+plan_corpus: $(METRICS_DIR)
+	@echo "Capturing Cypher plan corpus..."
+	@$(GO_CMD) run ./cmd/plancorpus
+
 # Metric targets
 $(METRICS_DIR):
 	@mkdir -p $(METRICS_DIR)
@@ -218,6 +222,7 @@ help:
 	@echo "  test_bench  - Run benchmark test"
 	@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 "  test_update - Update test cases"
 	@echo "  complexity  - Report cyclomatic complexity"
 	@echo "  crap        - Report CRAP scores from unit test coverage"

README.md

@@ -54,6 +54,8 @@ export CONNECTION_STRING="postgresql://dawgs:weneedbetterpasswords@localhost:654
 export CONNECTION_STRING="neo4j://neo4j:weneedbetterpasswords@localhost:7687"
 ```
 
+Neo4j connection strings may use `neo4j://`, `neo4j+s://`, or `neo4j+ssc://`; a single path segment selects the Neo4j database name.
+
 Use `make test` for unit tests only and `make test_integration` for integration tests only.
 
 ### Test Metrics
@@ -95,6 +97,24 @@ make quality FUZZ_REPORT=.coverage/fuzz.json MUTATION_REPORT=.coverage/mutation.
 `PG_CONNECTION_STRING` and `NEO4J_CONNECTION_STRING`. `make quality_bench` writes benchmark markdown and JSON captures
 for later baseline comparison.
 
+`make plan_corpus` captures plan diagnostics for the shared Cypher integration corpus. It accepts either
+`CONNECTION_STRING` for one backend or `PG_CONNECTION_STRING` and `NEO4J_CONNECTION_STRING` for both backends, then
+writes JSONL captures and markdown/JSON summaries under `.coverage/`.
+
+`go run ./cmd/graphbench` captures runtime diagnostics for the scale corpus under `benchmark/testdata/scale`. The
+current modes are `postgres_sql`, `local_traversal`, and `neo4j`; AGE is reference-design input only and is not a direct
+comparison mode yet. The command can emit JSONL records plus Markdown and JSON summaries, and can compare current timings
+against a previous JSONL baseline.
+
+PostgreSQL translates exact string property equality with a JSON string type guard and `properties ->>` extraction, so
+indexes created on expressions such as `properties ->> 'objectid'` and `properties ->> 'name'` can be used for selective
+anchors without matching JSON booleans or numbers. Simple relationship count fast paths depend on the schema's
+`kind_id`-first edge index for efficient typed counts.
+
+Substring and suffix predicates are intentionally not promoted to blanket schema indexes. PostgreSQL deployments can
+request explicit `TextSearchIndex`/trigram property indexes for fields that need `CONTAINS`, `STARTS WITH`, or
+`ENDS WITH`, but default schema assertion should wait until all suffix forms share one semantics-preserving lowering.
+
 Thresholds are report-only by default. To enforce the configured thresholds, run:
 
 ```bash

benchmark/testdata/scale/README.md

@@ -0,0 +1,28 @@
+# GraphBench Scale Corpus
+
+This corpus measures graph workload shapes, not general Cypher correctness.
+The shared integration corpus remains the source of backend-equivalent semantic
+coverage.
+
+Cases declare the values a query observes so benchmark reports can separate
+ID-only work from node, relationship, property, and path materialization.
+Current execution modes are `postgres_sql`, `local_traversal`, and `neo4j`.
+Apache AGE is intentionally not a benchmark mode here; it may appear only in
+`reference_design` notes as input for DAWGS design choices.
+
+Each JSON file contains a list of scale cases with:
+
+- `source`: the source corpus or workload family.
+- `dataset`: the fixture dataset to load from `integration/testdata`.
+- `name` and `category`: stable identifiers used in reports.
+- `cypher`: the Cypher query under test.
+- `parameters`: named parameter values.
+- `expected_rows`: the expected result cardinality.
+- `observes`: whether the query observes paths, nodes, relationships,
+  properties, or only IDs internally.
+- `candidate_modes`: the execution modes that should attempt the case.
+- `reference_design`: optional design notes, including AGE observations when
+  useful.
+
+Use `cmd/graphbench` to run this corpus and produce JSONL, Markdown, and JSON
+summaries.

benchmark/testdata/scale/cases/counts.json

@@ -0,0 +1,70 @@
+{
+  "cases": [
+    {
+      "name": "all_node_count",
+      "dataset": "base",
+      "category": "counts",
+      "cypher": "MATCH (n) RETURN count(n)",
+      "expected": {
+        "row_count": 1,
+        "result_kind": "scalar"
+      },
+      "observes": {
+        "paths": false,
+        "nodes": false,
+        "relationships": false,
+        "properties": false
+      },
+      "shape": {
+        "path_materialization_required": false
+      },
+      "candidate_modes": ["postgres_sql", "neo4j"],
+      "tags": ["count", "count-store"]
+    },
+    {
+      "name": "typed_node_count",
+      "dataset": "base",
+      "category": "counts",
+      "cypher": "MATCH (n:NodeKind1) RETURN count(n)",
+      "expected": {
+        "row_count": 1,
+        "result_kind": "scalar"
+      },
+      "observes": {
+        "paths": false,
+        "nodes": false,
+        "relationships": false,
+        "properties": false
+      },
+      "shape": {
+        "terminal_predicate": "node_kind",
+        "path_materialization_required": false
+      },
+      "candidate_modes": ["postgres_sql", "neo4j"],
+      "tags": ["count", "typed-count", "graph-stats"]
+    },
+    {
+      "name": "typed_edge_count",
+      "dataset": "base",
+      "category": "counts",
+      "cypher": "MATCH ()-[r:EdgeKind1]->() RETURN count(r)",
+      "expected": {
+        "row_count": 1,
+        "result_kind": "scalar"
+      },
+      "observes": {
+        "paths": false,
+        "nodes": false,
+        "relationships": false,
+        "properties": false
+      },
+      "shape": {
+        "edge_kinds": ["EdgeKind1"],
+        "path_materialization_required": false
+      },
+      "candidate_modes": ["postgres_sql", "neo4j"],
+      "tags": ["count", "typed-count", "graph-stats"]
+    }
+  ]
+}
+

benchmark/testdata/scale/cases/lookups.json

@@ -0,0 +1,54 @@
+{
+  "cases": [
+    {
+      "name": "objectid_exact_string_anchor",
+      "dataset": "base",
+      "category": "lookups",
+      "cypher": "MATCH (n:NodeKind1) WHERE n.objectid = $objectid RETURN id(n)",
+      "params": {
+        "objectid": "S-1-5-21-1"
+      },
+      "expected": {
+        "row_count": 1,
+        "result_kind": "id_set"
+      },
+      "observes": {
+        "paths": false,
+        "nodes": false,
+        "relationships": false,
+        "properties": false
+      },
+      "shape": {
+        "root_predicate": "selective_property",
+        "terminal_predicate": "node_kind",
+        "path_materialization_required": false
+      },
+      "candidate_modes": ["postgres_sql", "neo4j"],
+      "tags": ["property-anchor", "expression-index"]
+    },
+    {
+      "name": "boolean_property_filter",
+      "dataset": "base",
+      "category": "lookups",
+      "cypher": "MATCH (n:NodeKind1) WHERE n.enabled = true RETURN id(n)",
+      "expected": {
+        "row_count": 1,
+        "result_kind": "id_set"
+      },
+      "observes": {
+        "paths": false,
+        "nodes": false,
+        "relationships": false,
+        "properties": false
+      },
+      "shape": {
+        "root_predicate": "boolean_property",
+        "terminal_predicate": "node_kind",
+        "path_materialization_required": false
+      },
+      "candidate_modes": ["postgres_sql", "neo4j"],
+      "tags": ["property-filter"]
+    }
+  ]
+}
+

benchmark/testdata/scale/cases/shortest_paths.json

@@ -0,0 +1,61 @@
+{
+  "cases": [
+    {
+      "name": "shortest_distance_bound_pair",
+      "dataset": "base",
+      "category": "shortest_path",
+      "cypher": "MATCH p = shortestPath((s)-[*1..]->(e)) WHERE id(s) = $start_id AND id(e) = $end_id RETURN length(p)",
+      "node_params": {
+        "start_id": "n1",
+        "end_id": "n3"
+      },
+      "expected": {
+        "row_count": 1,
+        "result_kind": "scalar"
+      },
+      "observes": {
+        "paths": false,
+        "nodes": false,
+        "relationships": false,
+        "properties": false
+      },
+      "shape": {
+        "root_predicate": "bound_id",
+        "terminal_predicate": "bound_id",
+        "min_depth": 1,
+        "path_materialization_required": false
+      },
+      "candidate_modes": ["postgres_sql", "local_traversal", "neo4j"],
+      "tags": ["shortest-distance", "local-traversal-candidate"]
+    },
+    {
+      "name": "one_shortest_path_bound_pair",
+      "dataset": "base",
+      "category": "shortest_path",
+      "cypher": "MATCH p = shortestPath((s)-[*1..]->(e)) WHERE id(s) = $start_id AND id(e) = $end_id RETURN p LIMIT 1",
+      "node_params": {
+        "start_id": "n1",
+        "end_id": "n3"
+      },
+      "expected": {
+        "row_count": 1,
+        "result_kind": "path_set"
+      },
+      "observes": {
+        "paths": true,
+        "nodes": true,
+        "relationships": true,
+        "properties": true
+      },
+      "shape": {
+        "root_predicate": "bound_id",
+        "terminal_predicate": "bound_id",
+        "min_depth": 1,
+        "path_materialization_required": true
+      },
+      "candidate_modes": ["postgres_sql", "local_traversal", "neo4j"],
+      "tags": ["one-shortest-path", "local-traversal-candidate"]
+    }
+  ]
+}
+