feat: run_path_query — one read entry point for every PathQuery shape

grovedb-version/src/version/grovedb_versions.rs

@@ -35,6 +35,24 @@ pub struct GroveDBPathQueryMethodVersions {
     pub merge: FeatureVersion,
     pub query_items_at_path: FeatureVersion,
     pub should_add_parent_tree_at_path: FeatureVersion,
+    /// Whether `PathQuery` read modes (axis-ordered and sum-budget
+    /// reads, `Query::read_mode`) are served.
+    ///
+    /// - `0` (GROVE_V1..=V3): any `PathQuery` carrying a read mode is
+    ///   rejected with `NotSupported` at every read / prove / verify
+    ///   entry point. The vocabulary itself still encodes and decodes —
+    ///   the gate is about *serving*, so a v4-built query constructed
+    ///   ahead of activation fails closed instead of being misread as
+    ///   plain key selection (an axis read has empty items; running it
+    ///   as key selection would return an empty result masquerading as
+    ///   real absence, and a proof would attest to the wrong read).
+    /// - `1` (GROVE_V4+): `run_path_query` (and, as they land, the
+    ///   unified prove/verify dispatch) serve read-mode queries.
+    ///
+    /// Prover and verifier read the same slot, so there is no version
+    /// at which the two sides can disagree about whether a read-mode
+    /// shape exists.
+    pub unified_read_mode: FeatureVersion,
 }
 
 #[derive(Clone, Debug, Default)]
@@ -192,6 +210,11 @@ pub struct GroveDBOperationsQueryVersions {
     pub query_keys_optional: FeatureVersion,
     pub query_raw_keys_optional: FeatureVersion,
     pub follow_element: FeatureVersion,
+    /// The unified read dispatch (`GroveDb::run_path_query`). This is
+    /// the method's own algorithm slot; whether read-mode *shapes* are
+    /// served is the separate
+    /// `GroveDBPathQueryMethodVersions::unified_read_mode` gate.
+    pub run_path_query: FeatureVersion,
 }
 
 #[derive(Clone, Debug, Default)]

grovedb-version/src/version/v1.rs

@@ -148,6 +148,7 @@ pub const GROVE_V1: GroveVersion = GroveVersion {
                 query_keys_optional: 0,
                 query_raw_keys_optional: 0,
                 follow_element: 0,
+                run_path_query: 0,
             },
             proof: GroveDBOperationsProofVersions {
                 prove_query: 0,
@@ -204,6 +205,7 @@ pub const GROVE_V1: GroveVersion = GroveVersion {
             merge: 0,
             query_items_at_path: 0,
             should_add_parent_tree_at_path: 0,
+            unified_read_mode: 0,
         },
         replication: GroveDBReplicationVersions {
             get_subtrees_metadata: 0,

grovedb-version/src/version/v2.rs

@@ -148,6 +148,7 @@ pub const GROVE_V2: GroveVersion = GroveVersion {
                 query_keys_optional: 0,
                 query_raw_keys_optional: 0,
                 follow_element: 0,
+                run_path_query: 0,
             },
             proof: GroveDBOperationsProofVersions {
                 prove_query: 0,
@@ -204,6 +205,7 @@ pub const GROVE_V2: GroveVersion = GroveVersion {
             merge: 0,
             query_items_at_path: 0,
             should_add_parent_tree_at_path: 0,
+            unified_read_mode: 0,
         },
         replication: GroveDBReplicationVersions {
             get_subtrees_metadata: 0,

grovedb-version/src/version/v3.rs

@@ -152,6 +152,7 @@ pub const GROVE_V3: GroveVersion = GroveVersion {
                 query_keys_optional: 0,
                 query_raw_keys_optional: 0,
                 follow_element: 0,
+                run_path_query: 0,
             },
             proof: GroveDBOperationsProofVersions {
                 prove_query: 0,
@@ -208,6 +209,7 @@ pub const GROVE_V3: GroveVersion = GroveVersion {
             merge: 0,
             query_items_at_path: 0,
             should_add_parent_tree_at_path: 0,
+            unified_read_mode: 0,
         },
         replication: GroveDBReplicationVersions {
             get_subtrees_metadata: 0,

grovedb-version/src/version/v4.rs

@@ -32,6 +32,14 @@
 //!   flips a rejected/accepted outcome and because deriving the state root
 //!   costs the prover extra storage reads and hash calls.
 //!
+//! - `path_query_methods.unified_read_mode: 1` — `PathQuery` read modes
+//!   (axis-ordered and sum-budget reads carried in `Query::read_mode`) are
+//!   served by the unified dispatch (`run_path_query`, and the unified
+//!   prove/verify as they land). V1..V3 reject any read-mode-bearing query
+//!   with `NotSupported` at every entry point — those versions also reject
+//!   the version-2 `Query` wire encoding outright, so the slot's `0` value
+//!   is the in-process mirror of that fail-closed decode.
+//!
 //! Note that `GroveVersion::latest()` resolves to this version, so anything
 //! defaulting to "latest" — tests, benchmarks, tools — exercises every gate
 //! listed above rather than V3 behaviour.
@@ -202,6 +210,7 @@ pub const GROVE_V4: GroveVersion = GroveVersion {
                 query_keys_optional: 0,
                 query_raw_keys_optional: 0,
                 follow_element: 0,
+                run_path_query: 0,
             },
             proof: GroveDBOperationsProofVersions {
                 prove_query: 0,
@@ -258,6 +267,7 @@ pub const GROVE_V4: GroveVersion = GroveVersion {
             merge: 0,
             query_items_at_path: 0,
             should_add_parent_tree_at_path: 0,
+            unified_read_mode: 1,
         },
         replication: GroveDBReplicationVersions {
             get_subtrees_metadata: 0,

grovedb/src/lib.rs

@@ -241,6 +241,11 @@ use grovedb_storage::{Storage, StorageContext};
 use grovedb_version::version::GroveVersion;
 #[cfg(feature = "minimal")]
 use grovedb_visualize::DebugByteVectors;
+/// The unified read dispatch's result types. `operations::get` is
+/// crate-private, so without this re-export `run_path_query` would be
+/// callable from outside the crate but its return type unnameable.
+#[cfg(feature = "minimal")]
+pub use operations::get::{AxisAggregateValue, PathQueryRun};
 #[cfg(any(feature = "minimal", feature = "verify"))]
 pub use query::{
     aggregate_sum_path_query::AggregateSumPathQuery, AggregateKind, GroveBranchQueryResult,

grovedb/src/operations/get/mod.rs

@@ -4,8 +4,10 @@
 mod average_case;
 
 mod query;
+mod run_path_query;
 use grovedb_storage::Storage;
 pub use query::QueryItemOrSumReturnType;
+pub use run_path_query::{AxisAggregateValue, PathQueryRun};
 #[cfg(feature = "estimated_costs")]
 mod worst_case;