Add PreparedQuery for parse-once, execute-many Cypher reads

[Copilot]

This introduces a prepared-query API for read-only Cypher execution so query parsing/validation can happen once and execution can be repeated efficiently, including parameterized runs.

• New public API: PreparedQuery

  • Adds PreparedQuery::parse to parse + validate read-only queries once.
  • Adds repeated execution entry points:
    • execute
    • execute_params
    • execute_with_strategy
    • execute_with_strategy_params
  • Re-exports PreparedQuery from the crate root.

• Execution path update

  • Refactors read execution to run against a borrowed planned query (&CypherQuery) instead of requiring ownership.
  • Avoids cloning the planned query during prepared execution.

• Behavioral coverage

  • Adds integration tests to verify prepared execution returns the same rows as direct cypher/cypher_params calls for equivalent inputs.
  • Adds a parse-time rejection test for mutation clauses in prepared queries.

let prepared = PreparedQuery::parse(
    "MATCH (p:Person) WHERE p.name = $name RETURN p.name AS name"
)?;

let mut params = Parameters::new();
params.insert("name".into(), CypherValue::String("Alice".into()));

let rows = prepared.execute_params(&graph, &params)?;

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• extension.ladybugdb.com
  • Triggering command: /opt/hostedtoolcache/node/24.14.1/x64/bin/node /opt/hostedtoolcache/node/24.14.1/x64/bin/node /home/REDACTED/.npm/_npx/5e786f48223a616c/node_modules/gitnexus/scripts/install-duckdb-extension.mjs fts 17179869184 /home/REDACTED/.cache/node-gyp/24.14.1/deps/zlib -I /home/REDACTED/.cache/node-gyp/24.14.1/deps/v8/include -I ../src -I ../../../../node-addon-api --64 23a6�� k/petgraph-decypher/petgraph-decypher/target/debug/deps/thiserror_impl-dbf14981191e3e77.thiserrobash k/petgraph-decypher/petgraph-decypher/target/debug/deps/thiserror_impl-dbf14981191e3e77.thiserro--norc ache/node/24.14.1/x64/lib/node_modules/npm/node_modules/@npmcli/run-script/lib/node-gyp-bin/node--noprofile otlin_binding/sras k/petgraph-decyp-I k/petgraph-decyp/home/REDACTED/.cache/node-gyp/24.14.1/include/node k/petgraph-decyp-I (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull request overview

This PR introduces a new public PreparedQuery API to support parsing/validating read-only Cypher once and executing it repeatedly (optionally parameterized), and refactors the read execution pipeline to accept a borrowed planned query (&CypherQuery) to reduce ownership churn during execution.

Changes:

• Added PreparedQuery with parse + multiple execution entry points (default/strategy, with/without params).
• Refactored ReadQueryExecutor::execute and call sites to execute against &CypherQuery rather than consuming a CypherQuery.
• Added integration tests asserting prepared execution matches direct execution results and that mutations are rejected at parse time.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
tests/query_tests.rs	Adds integration tests covering prepared-query execution equivalence and mutation rejection.
src/query.rs	Introduces PreparedQuery and refactors read execution to operate on borrowed planned queries.
src/lib.rs	Re-exports PreparedQuery from the crate root as part of the public API.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.