address review

Author: roberto-bayardo

storage/src/bitmap/authenticated.rs

@@ -459,10 +459,10 @@ impl<E: Context, D: Digest, const N: usize, S: Strategy> MerkleizedBitMap<E, D,
     /// Return an inclusion proof for the specified bit, along with the chunk of the bitmap
     /// containing that bit. The proof can be used to prove any bit in the chunk.
     ///
-    /// The bitmap proof stores the number of bits in the bitmap within the `size` field of the
-    /// proof instead of MMR size since the underlying MMR's size does not reflect the number of
-    /// bits in any partial chunk. The underlying MMR size can be derived from the number of
-    /// bits as `leaf_num_to_pos(proof.size / BitMap<_, N>::CHUNK_SIZE_BITS)`.
+    /// The bitmap proof stores the number of bits in the bitmap within the proof's `leaves` field
+    /// instead of the underlying MMR leaf count, since the MMR does not reflect the number of bits
+    /// in any partial chunk. The underlying MMR size can be derived from the number of bits as
+    /// `leaf_num_to_pos(proof.leaves / BitMap<_, N>::CHUNK_SIZE_BITS)`.
     ///
     /// # Errors
     ///

storage/src/journal/authenticated.rs

@@ -95,14 +95,21 @@ impl<F: Family, H: Hasher, Item: Encode + Send + Sync, S: Strategy>
 
     /// Merkleize the batch.
     /// `base` provides committed node data as fallback during hash computation.
-    pub fn merkleize(mut self, base: &Mem<F, H::Digest>) -> MerkleizedBatchArc<F, H, Item, S> {
-        let items = Arc::new(core::mem::take(&mut self.items));
-        let merkle = self.inner.merkleize(base, &self.hasher);
-        let ancestor_items = Self::collect_ancestor_items(&self.parent);
+    pub fn merkleize(self, base: &Mem<F, H::Digest>) -> MerkleizedBatchArc<F, H, Item, S> {
+        let Self {
+            inner,
+            hasher,
+            items,
+            parent,
+        } = self;
+
+        let items = Arc::new(items);
+        let merkle = inner.merkleize(base, &hasher);
+        let ancestor_items = Self::collect_ancestor_items(&parent);
         Arc::new(MerkleizedBatch {
             inner: merkle,
             items,
-            parent: self.parent.as_ref().map(Arc::downgrade),
+            parent: parent.as_ref().map(Arc::downgrade),
             ancestor_items,
         })
     }
@@ -593,7 +600,7 @@ where
     }
 
     /// Generate a historical proof with respect to the state of the Merkle structure when it had
-    /// `historical_leaves` leaves, using `spec` to determine peak bagging.
+    /// `historical_leaves` leaves.
     ///
     /// Returns a proof and the items corresponding to the leaves in the range `start_loc..end_loc`,
     /// where `end_loc` is the minimum of `historical_leaves` and `start_loc + max_ops`.

storage/src/merkle/mem.rs

@@ -264,7 +264,9 @@ impl<F: Family, D: Digest> Mem<F, D> {
         self.pruning_boundary = pos;
     }
 
-    /// Return an inclusion proof for the element at location `loc` using an explicit root spec.
+    /// Return an inclusion proof for the element at location `loc`.
+    ///
+    /// The proof commits to `inactive_peaks`; peak bagging is selected by `hasher`.
     ///
     /// # Errors
     ///
@@ -287,8 +289,9 @@ impl<F: Family, D: Digest> Mem<F, D> {
             })
     }
 
-    /// Return an inclusion proof for all elements within the provided `range` of locations
-    /// using an explicit root spec.
+    /// Return an inclusion proof for all elements within the provided `range` of locations.
+    ///
+    /// The proof commits to `inactive_peaks`; peak bagging is selected by `hasher`.
     ///
     /// # Errors
     ///
@@ -1149,7 +1152,7 @@ mod tests {
         );
     }
 
-    fn split_root_spec_matches_recompute<F: Family>() {
+    fn split_root_matches_recompute<F: Family>() {
         let hasher: H = Standard::new();
         let plain = build::<F>(&hasher, 49);
         let inactive_peaks = 1;
@@ -1263,8 +1266,8 @@ mod tests {
         apply_batch_overwrite_only_ancestor::<crate::mmr::Family>();
     }
     #[test]
-    fn mmr_split_root_spec_matches_recompute() {
-        split_root_spec_matches_recompute::<crate::mmr::Family>();
+    fn mmr_split_root_matches_recompute() {
+        split_root_matches_recompute::<crate::mmr::Family>();
     }
 
     // --- MMB tests ---
@@ -1362,7 +1365,7 @@ mod tests {
         apply_batch_overwrite_only_ancestor::<crate::mmb::Family>();
     }
     #[test]
-    fn mmb_split_root_spec_matches_recompute() {
-        split_root_spec_matches_recompute::<crate::mmb::Family>();
+    fn mmb_split_root_matches_recompute() {
+        split_root_matches_recompute::<crate::mmb::Family>();
     }
 }

storage/src/merkle/persisted/full.rs

@@ -243,7 +243,8 @@ impl<F: Family, E: RStorage + Clock + Metrics, D: Digest, S: Strategy> Merkle<F,
 
     /// Read-only peek at the persisted structure's root and boundaries.
     ///
-    /// The root spec must match the spec used by the caller for the persisted structure.
+    /// `inactive_peaks` and `hasher.root_bagging()` must match the root shape expected by the
+    /// caller for the persisted structure.
     ///
     /// Returns `Ok(None)` when:
     /// - Journal size is structurally invalid and would require a rewind (i.e.
@@ -994,7 +995,9 @@ impl<F: Family, E: RStorage + Clock + Metrics + Sync, D: Digest, S: Strategy>
 
 impl<F: Family, E: RStorage + Clock + Metrics, D: Digest, S: Strategy> Merkle<F, E, D, S> {
     /// Return an inclusion proof for the element at the location `loc` against a historical
-    /// state with `leaves` leaves, using `spec` to determine peak bagging.
+    /// state with `leaves` leaves.
+    ///
+    /// The proof commits to `inactive_peaks`; peak bagging is selected by `hasher`.
     ///
     /// # Errors
     ///
@@ -1019,7 +1022,9 @@ impl<F: Family, E: RStorage + Clock + Metrics, D: Digest, S: Strategy> Merkle<F,
     }
 
     /// Return an inclusion proof for the elements in `range` against a historical state with
-    /// `leaves` leaves, using `spec` to determine peak bagging.
+    /// `leaves` leaves.
+    ///
+    /// The proof commits to `inactive_peaks`; peak bagging is selected by `hasher`.
     ///
     /// # Errors
     ///
@@ -1050,7 +1055,9 @@ impl<F: Family, E: RStorage + Clock + Metrics, D: Digest, S: Strategy> Merkle<F,
     }
 
     /// Return an inclusion proof for the element at the location `loc` that can be verified against
-    /// the current root, using `spec` to determine peak bagging.
+    /// the current root.
+    ///
+    /// The proof commits to `inactive_peaks`; peak bagging is selected by `hasher`.
     ///
     /// Unlike the in-memory `Mem::proof`, this async method can read from the backing journal for
     /// nodes that have been synced out of memory.
@@ -1074,8 +1081,9 @@ impl<F: Family, E: RStorage + Clock + Metrics, D: Digest, S: Strategy> Merkle<F,
         self.range_proof(hasher, loc..loc + 1, inactive_peaks).await
     }
 
-    /// Return an inclusion proof for the elements within the specified location range, using
-    /// `spec` to determine peak bagging.
+    /// Return an inclusion proof for the elements within the specified location range.
+    ///
+    /// The proof commits to `inactive_peaks`; peak bagging is selected by `hasher`.
     ///
     /// Unlike the in-memory `Mem::range_proof`, this async method can read from the backing
     /// journal for nodes that have been synced out of memory.

storage/src/merkle/proof.rs

@@ -54,12 +54,12 @@ pub enum ReconstructionError {
 ///    in depth-first (forward consumption) order for each range peak.
 ///
 /// Multi-proofs use a different layout: `digests` contains the sorted set of node digests required
-/// by the selected root spec, including individual prefix peak digests rather than a folded prefix
-/// accumulator. This layout is intentionally position-keyed: every multi-proof digest corresponds
-/// to a concrete Merkle node position. For `BackwardFold`, this may include active suffix peaks that
-/// a single range proof could collapse into a smaller synthetic suffix accumulator. We keep the
-/// extra active peaks so multi-proofs and proof stores can stay simple and derive witnesses from
-/// positions alone.
+/// by the requested `inactive_peaks` and bagging policy, including individual prefix peak digests
+/// rather than a folded prefix accumulator. This layout is intentionally position-keyed: every
+/// multi-proof digest corresponds to a concrete Merkle node position. For `BackwardFold`, this may
+/// include active suffix peaks that a single range proof could collapse into a smaller synthetic
+/// suffix accumulator. We keep the extra active peaks so multi-proofs and proof stores can stay
+/// simple and derive witnesses from positions alone.
 #[derive(Clone, Debug, Eq)]
 pub struct Proof<F: Family, D: Digest> {
     /// The total number of leaves in the data structure. For MMR proofs, this is the number of
@@ -175,7 +175,11 @@ impl<F: Family, D: Digest> Proof<F, D> {
 
     /// Returns true if this proof's `inactive_peaks` field matches the canonical value derived
     /// from `size` and `inactivity_floor`.
-    pub fn matches_canonical_spec(&self, size: Position<F>, inactivity_floor: Location<F>) -> bool {
+    pub fn matches_canonical_inactive_peaks(
+        &self,
+        size: Position<F>,
+        inactivity_floor: Location<F>,
+    ) -> bool {
         self.inactive_peaks == F::inactive_peaks(size, inactivity_floor)
     }
 
@@ -343,7 +347,10 @@ impl<F: Family, D: Digest> Proof<F, D> {
         Ok(collected_digests)
     }
 
-    /// Verify this proof and the pinned nodes against `root` using `spec`.
+    /// Verify this proof and the pinned nodes against `root`.
+    ///
+    /// The proof's `inactive_peaks` field commits to the split boundary; peak bagging is selected
+    /// by `hasher`.
     ///
     /// The `pinned_nodes` are the peak digests of the sub-structure at `start_loc`, in the order
     /// returned by `Family::nodes_to_pin`. The proof authenticates the prefix `[0, start_loc)` via:
@@ -1171,24 +1178,24 @@ mod tests {
         Standard::with_bagging(bagging)
     }
 
-    fn push_unique_spec(specs: &mut Vec<(Bagging, usize)>, spec: (Bagging, usize)) {
-        if !specs.contains(&spec) {
-            specs.push(spec);
+    fn push_unique_shape(shapes: &mut Vec<(Bagging, usize)>, shape: (Bagging, usize)) {
+        if !shapes.contains(&shape) {
+            shapes.push(shape);
         }
     }
 
-    fn supported_root_specs<F: Family>(leaves: Location<F>) -> Vec<(Bagging, usize)> {
+    fn supported_root_shapes<F: Family>(leaves: Location<F>) -> Vec<(Bagging, usize)> {
         let peak_count = F::peaks(F::location_to_position(leaves)).count();
-        let mut specs = Vec::new();
+        let mut shapes = Vec::new();
 
-        push_unique_spec(&mut specs, (Bagging::ForwardFold, 0));
-        push_unique_spec(&mut specs, (Bagging::BackwardFold, 0));
+        push_unique_shape(&mut shapes, (Bagging::ForwardFold, 0));
+        push_unique_shape(&mut shapes, (Bagging::BackwardFold, 0));
         for inactive_peaks in 0..=peak_count {
-            push_unique_spec(&mut specs, (Bagging::ForwardFold, inactive_peaks));
-            push_unique_spec(&mut specs, (Bagging::BackwardFold, inactive_peaks));
+            push_unique_shape(&mut shapes, (Bagging::ForwardFold, inactive_peaks));
+            push_unique_shape(&mut shapes, (Bagging::BackwardFold, inactive_peaks));
         }
 
-        specs
+        shapes
     }
 
     fn inactive_leaf_floor<F: Family>(leaves: Location<F>, inactive_peaks: usize) -> u64 {
@@ -1198,7 +1205,7 @@ mod tests {
             .sum()
     }
 
-    fn active_start_for_spec<F: Family>(
+    fn active_start_for_shape<F: Family>(
         leaves: Location<F>,
         inactive_peaks: usize,
         width: u64,
@@ -1210,13 +1217,13 @@ mod tests {
         Location::new(*leaves - width)
     }
 
-    fn range_proofs_verify_for_supported_root_specs<F: Family>() {
+    fn range_proofs_verify_for_supported_root_shapes<F: Family>() {
         let mem = build_raw::<F>(&H::new(), 123);
         let leaves = mem.leaves();
 
-        for (bagging, inactive_peaks) in supported_root_specs::<F>(leaves) {
+        for (bagging, inactive_peaks) in supported_root_shapes::<F>(leaves) {
             let hasher = hasher_for_bagging(bagging);
-            let range_start = active_start_for_spec::<F>(leaves, inactive_peaks, 3);
+            let range_start = active_start_for_shape::<F>(leaves, inactive_peaks, 3);
             let range = range_start..range_start + 3;
             let root = mem.root(&hasher, inactive_peaks).unwrap();
             let elements: Vec<_> = (*range.start..*range.end)
@@ -1257,13 +1264,13 @@ mod tests {
         }
     }
 
-    fn multi_proofs_verify_for_supported_root_specs<F: Family>() {
+    fn multi_proofs_verify_for_supported_root_shapes<F: Family>() {
         let mem = build_raw::<F>(&H::new(), 123);
         let leaves = mem.leaves();
 
-        for (bagging, inactive_peaks) in supported_root_specs::<F>(leaves) {
+        for (bagging, inactive_peaks) in supported_root_shapes::<F>(leaves) {
             let hasher = hasher_for_bagging(bagging);
-            let first = active_start_for_spec::<F>(leaves, inactive_peaks, 12);
+            let first = active_start_for_shape::<F>(leaves, inactive_peaks, 12);
             let locations = [first, first + 5, first + 11];
             let nodes = nodes_required_for_multi_proof(leaves, inactive_peaks, bagging, &locations)
                 .expect("test locations valid");
@@ -1358,7 +1365,7 @@ mod tests {
     }
 
     #[test]
-    fn full_backward_root_spec_proves_like_split_zero() {
+    fn full_backward_root_proves_like_split_zero() {
         let hasher: H = Standard::backward();
         let mem = build_raw::<mmb::Family>(&hasher, 123);
         let range = Location::new(2)..Location::new(3);
@@ -1403,7 +1410,7 @@ mod tests {
             &full_backward_root,
         ));
 
-        // Split { inactive_peaks: 0 } is byte-identical to Full when inactive_peaks == 0.
+        // A zero inactive boundary is byte-identical to the corresponding full root.
         let split_root_value = mem.root(&hasher, 0).unwrap();
         assert_eq!(full_backward_root, split_root_value);
         let split_proof: Result<Proof<mmb::Family, D>, Error<mmb::Family>> = build_range_proof(
@@ -2549,12 +2556,12 @@ mod tests {
         range_proof_reconstruction::<mmr::Family>();
     }
     #[test]
-    fn mmr_range_proofs_verify_for_supported_root_specs() {
-        range_proofs_verify_for_supported_root_specs::<mmr::Family>();
+    fn mmr_range_proofs_verify_for_supported_root_shapes() {
+        range_proofs_verify_for_supported_root_shapes::<mmr::Family>();
     }
     #[test]
-    fn mmr_multi_proofs_verify_for_supported_root_specs() {
-        multi_proofs_verify_for_supported_root_specs::<mmr::Family>();
+    fn mmr_multi_proofs_verify_for_supported_root_shapes() {
+        multi_proofs_verify_for_supported_root_shapes::<mmr::Family>();
     }
     #[test]
     fn mmr_verify_element_inclusion() {
@@ -2642,12 +2649,12 @@ mod tests {
         range_proof_reconstruction::<mmb::Family>();
     }
     #[test]
-    fn mmb_range_proofs_verify_for_supported_root_specs() {
-        range_proofs_verify_for_supported_root_specs::<mmb::Family>();
+    fn mmb_range_proofs_verify_for_supported_root_shapes() {
+        range_proofs_verify_for_supported_root_shapes::<mmb::Family>();
     }
     #[test]
-    fn mmb_multi_proofs_verify_for_supported_root_specs() {
-        multi_proofs_verify_for_supported_root_specs::<mmb::Family>();
+    fn mmb_multi_proofs_verify_for_supported_root_shapes() {
+        multi_proofs_verify_for_supported_root_shapes::<mmb::Family>();
     }
     #[test]
     fn mmb_verify_element_inclusion() {

storage/src/merkle/read.rs

@@ -11,7 +11,7 @@ use core::ops::Range;
 /// construction is intentionally *not* part of the trait: every concrete implementation exposes
 /// inherent `proof` / `range_proof` methods that take an explicit `inactive_peaks` count and read
 /// the bagging policy from the supplied [`crate::merkle::hasher::Hasher`], so callers cannot
-/// accidentally pair a split-spec root with a forward-fold proof from the same state.
+/// accidentally pair a split root with a forward-fold proof from the same state.
 pub trait Readable: Send + Sync {
     /// The Merkle family implemented by this structure.
     type Family: Family;

storage/src/merkle/verification.rs

@@ -273,8 +273,9 @@ impl<F: Family, D: Digest> ProofStore<F, D> {
     }
 }
 
-/// Return a range proof for the nodes corresponding to the given location range, using `spec`
-/// to determine peak bagging.
+/// Return a range proof for the nodes corresponding to the given location range.
+///
+/// The proof commits to `inactive_peaks`; peak bagging is selected by `hasher`.
 ///
 /// # Errors
 ///
@@ -345,8 +346,10 @@ pub async fn historical_range_proof<
     )
 }
 
-/// Return an inclusion proof for the elements at the specified locations using `spec`. This is
-/// analogous to range_proof but supports non-contiguous locations.
+/// Return an inclusion proof for the elements at the specified locations. This is analogous to
+/// range_proof but supports non-contiguous locations.
+///
+/// The proof commits to `inactive_peaks`; peak bagging is supplied by `bagging`.
 ///
 /// The order of positions does not affect the output (sorted internally).
 ///

storage/src/qmdb/any/db.rs

@@ -340,8 +340,8 @@ where
     ///
     /// When this database is configured with `split_root: true`, `historical_size` must be a
     /// commit-boundary size: the operation at `historical_size - 1` must itself be a commit
-    /// op declaring the governing inactivity floor. With `split_root: false` the spec does
-    /// not depend on the floor and any retained `historical_size` works.
+    /// op declaring the governing inactivity floor. With `split_root: false`, historical proof
+    /// roots do not depend on the floor and any retained `historical_size` works.
     ///
     /// # Errors
     ///

storage/src/qmdb/any/mod.rs

@@ -847,7 +847,7 @@ pub(crate) mod test {
 
         // Apply two single-write batches and capture the commit-boundary size after the
         // first batch. `historical_proof` requires the historical size to land on a commit
-        // boundary when the db uses a split-root spec.
+        // boundary when the db commits to an inactive peak boundary.
         let mut historical_op_count = Location::new(0);
         for i in 0u64..2 {
             let k = Sha256::hash(&i.to_be_bytes());
@@ -987,7 +987,7 @@ pub(crate) mod test {
 
         // Apply a sequence of single-write batches and record the commit-boundary size
         // reached after each. `historical_proof` requires the historical size to be a
-        // commit boundary when the db uses a split-root spec, so we anchor each test on
+        // commit boundary when the db commits to an inactive peak boundary, so we anchor each test on
         // one of the boundaries we recorded here rather than hardcoding sizes that depend
         // on internal floor-raising behavior.
         let initial_size = db.bounds().await.end;