Merge pull request #3250 from ProvableHQ/mohammadfawaz/query_doc_followup

docs/test(query): qualify Stack snapshot claim + add name-collision tests

Author: vicsn

synthesizer/process/src/query.rs

@@ -55,19 +55,17 @@ impl<N: Network> Process<N> {
 }
 
 /// Evaluates a query function against historic finalize-store state at the given block
-/// `height`. Mapping reads route through `FinalizeStore::get_historical_mapping_value`, which
-/// reconstructs the value applicable at `height` from the per-key update log (a confirmed-only
-/// table — entries are only written during finalize, never modified). Pinning every read to
-/// `height` therefore gives true snapshot semantics: block production advancing past `height`
-/// during evaluation cannot disturb the result, and we don't need to take an atomic batch on
-/// the store (so this path doesn't contend with block finalization either).
+/// `height`. Mapping reads route through `FinalizeStore::get_historical_mapping_value` and
+/// are snapshot-consistent at `height` without contending with block finalization.
 ///
-/// `state` is supplied by the caller — typically `VM::evaluate_query_at_height` constructs it
-/// from the historic block at `height` so query operands reading block metadata
-/// (`block.height`, `block.timestamp`, the random seed) reflect that block.
+/// `state` is supplied by the caller — typically built from the historic block at `height`
+/// so block-metadata operands reflect that block.
 ///
-/// Available only when snarkVM is built with `--features history`. snarkOS calls this with
-/// `current_block_height()` for "latest", or any earlier height for historic queries.
+/// Caveat: the live `Stack` has interior mutability, so a concurrent redeploy of the same
+/// program could perturb its structural caches mid-query. Mapping values are pinned at
+/// `height`; program structure is not. Known gap — see `VM::evaluate_query_at_height`.
+///
+/// Available only with `--features history`.
 pub fn evaluate_query_at_height<N: Network, P: FinalizeStorage<N>>(
     state: FinalizeGlobalState,
     store: &FinalizeStore<N, P>,

synthesizer/program/src/parse.rs

@@ -333,6 +333,61 @@ query uses_call:
         assert!(result.is_err(), "expected program parse to fail when query contains 'call'");
     }
 
+    #[test]
+    fn test_program_rejects_duplicate_query_names() {
+        let result = Program::<CurrentNetwork>::from_str(
+            r"
+program dup_query.aleo;
+
+query foo:
+    add 0u64 1u64 into r0;
+    output r0 as u64.public;
+
+query foo:
+    add 0u64 2u64 into r0;
+    output r0 as u64.public;",
+        );
+        assert!(result.is_err(), "expected program parse to fail with two queries named 'foo'");
+    }
+
+    #[test]
+    fn test_program_rejects_query_name_colliding_with_function() {
+        let result = Program::<CurrentNetwork>::from_str(
+            r"
+program qf_collision.aleo;
+
+function foo:
+    input r0 as u64.private;
+    output r0 as u64.private;
+
+query foo:
+    add 0u64 1u64 into r0;
+    output r0 as u64.public;",
+        );
+        assert!(result.is_err(), "expected program parse to fail when a query reuses a function name");
+    }
+
+    #[test]
+    fn test_program_rejects_query_name_colliding_with_closure() {
+        let result = Program::<CurrentNetwork>::from_str(
+            r"
+program qc_collision.aleo;
+
+closure foo:
+    input r0 as field;
+    output r0 as field;
+
+function noop:
+    input r0 as u64.private;
+    output r0 as u64.private;
+
+query foo:
+    add 0u64 1u64 into r0;
+    output r0 as u64.public;",
+        );
+        assert!(result.is_err(), "expected program parse to fail when a query reuses a closure name");
+    }
+
     #[test]
     fn test_program_parse_function_zero_inputs() -> Result<()> {
         // Initialize a new program.

synthesizer/src/vm/mod.rs

@@ -331,25 +331,19 @@ impl<N: Network, C: ConsensusStorage<N>> VM<N, C> {
     }
 
     /// Evaluates a query function against finalize-store state at the given block `height`.
-    /// Returns the typed outputs (no `(height, outputs)` tuple — the caller already supplied
-    /// the height).
+    /// Returns the typed outputs.
     ///
-    /// All mapping reads are pinned to `height` via the finalize store's per-key historical
-    /// update map (entries at any given height are immutable once written), so block production
-    /// advancing past `height` mid-evaluation cannot disturb the result. The
-    /// `FinalizeGlobalState` is also reconstructed from the block at `height`, so query operands
-    /// reading block metadata see that block's values.
+    /// Mapping reads are pinned to `height` via the per-key historical update map, and the
+    /// `FinalizeGlobalState` is reconstructed from the block at `height`. Available only with
+    /// `--features history`.
     ///
-    /// snarkOS calls this with `current_block_height()` for "latest" semantics, or any earlier
-    /// height for historic queries. Available only when snarkVM is built with `--features history`
-    /// — the per-height update map that pins reads is only populated under that feature.
+    /// snarkOS calls this with `current_block_height()` for "latest", or any earlier height
+    /// for historic queries. `height` must satisfy `height <= current_block_height()`.
     ///
-    /// `height` must satisfy `height <= current_block_height()`. Reading a future height
-    /// returns "no block exists" rather than a misleading None.
-    ///
-    /// Concurrency: this call does NOT take `self.process.lock()` (which would serialize
-    /// queries against block production); it relies on `Arc<Stack<N>>` immutability and on the
-    /// fact that historic-table entries are immutable.
+    /// Caveat: the `Stack` itself uses interior mutability, so a concurrent redeploy of the
+    /// same program could perturb its structural caches mid-query. Mapping values are
+    /// snapshot-consistent at `height`; program structure is not. Known gap; a future
+    /// `StackSnapshot`-style fix would close it.
     #[cfg(feature = "history")]
     #[inline]
     pub fn evaluate_query_at_height(