Implement ShardTree::frontier() to extract a full-depth NonEmptyFrontier

Adds a frontier_ommers() helper to LocatedPrunableTree that returns the
raw (position, leaf, ommers) without from_parts validation, enabling
ShardTree::frontier() to assemble a complete frontier by combining
within-shard ommers with sibling subtree root hashes above the shard level.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: nuttycom

shardtree/src/lib.rs

@@ -160,6 +160,41 @@ impl<
         Ok(result)
     }
 
+    /// Returns the frontier of the tree, if the tree is nonempty and the frontier
+    /// can be determined from the available data.
+    ///
+    /// The frontier consists of the rightmost leaf and the ommers (sibling hashes)
+    /// needed to compute the root. This method assembles ommers from within the
+    /// last shard (below `SHARD_HEIGHT`) and from sibling subtree roots above the
+    /// shard level.
+    pub fn frontier(&self) -> Result<Option<NonEmptyFrontier<H>>, ShardTreeError<S::Error>> {
+        let last_shard = self.store.last_shard().map_err(ShardTreeError::Storage)?;
+        let last_shard = match last_shard {
+            Some(s) => s,
+            None => return Ok(None),
+        };
+
+        let (position, leaf, mut ommers) = match last_shard.frontier_ommers() {
+            Some(parts) => parts,
+            None => return Ok(None),
+        };
+
+        // Walk from the shard root address up to the tree root, collecting ommers
+        // from sibling subtrees above the shard level.
+        let mut cur_addr = last_shard.root_addr;
+        while cur_addr.level() < Level::from(DEPTH) {
+            if cur_addr.is_right_child() {
+                let sibling_hash = self.root(cur_addr.sibling(), position + 1)?;
+                ommers.push(sibling_hash);
+            }
+            cur_addr = cur_addr.parent();
+        }
+
+        NonEmptyFrontier::from_parts(position, leaf, ommers)
+            .map(Some)
+            .map_err(|_| ShardTreeError::Query(QueryError::TreeIncomplete(vec![Self::root_addr()])))
+    }
+
     /// Inserts a new root into the tree at the given address.
     ///
     /// The level associated with the given address may not exceed `DEPTH`.
@@ -1472,6 +1507,110 @@ mod tests {
         check_rewind_remove_mark(new_tree);
     }
 
+    #[test]
+    fn frontier_empty_tree() {
+        let tree: ShardTree<MemoryShardStore<String, u32>, 4, 3> =
+            ShardTree::new(MemoryShardStore::empty(), 100);
+        assert_eq!(tree.frontier().unwrap(), None);
+    }
+
+    #[test]
+    fn frontier_single_leaf() {
+        let mut tree: ShardTree<MemoryShardStore<String, u32>, 4, 3> =
+            ShardTree::new(MemoryShardStore::empty(), 100);
+        tree.append("a".to_string(), Retention::Ephemeral).unwrap();
+
+        let frontier = tree.frontier().unwrap().unwrap();
+        assert_eq!(
+            frontier,
+            NonEmptyFrontier::from_parts(Position::from(0), "a".to_string(), vec![]).unwrap()
+        );
+    }
+
+    #[test]
+    fn frontier_within_single_shard() {
+        // Insert a frontier at position 5 within the first shard (SHARD_HEIGHT=3).
+        // Position 5 = binary 101: ommers at level 0 ("e") and level 2 ("abcd").
+        let original = NonEmptyFrontier::from_parts(
+            Position::from(5),
+            "f".to_string(),
+            vec!["e".to_string(), "abcd".to_string()],
+        )
+        .unwrap();
+
+        let mut tree: ShardTree<MemoryShardStore<String, u32>, 4, 3> =
+            ShardTree::new(MemoryShardStore::empty(), 100);
+        tree.insert_frontier_nodes(original.clone(), Retention::Ephemeral)
+            .unwrap();
+
+        let frontier = tree.frontier().unwrap().unwrap();
+        assert_eq!(frontier, original);
+    }
+
+    #[test]
+    fn frontier_multi_shard() {
+        // Insert a frontier at position 9, which is in the second shard (SHARD_HEIGHT=3).
+        // Position 9 = binary 1001: ommers at level 0 ("i") and level 3 ("abcdefgh").
+        // Level 0 ommer "i" is within the shard; level 3 ommer "abcdefgh" is the
+        // sibling shard's root above the shard level.
+        let original = NonEmptyFrontier::from_parts(
+            Position::from(9),
+            "j".to_string(),
+            vec!["i".to_string(), "abcdefgh".to_string()],
+        )
+        .unwrap();
+
+        let mut tree: ShardTree<MemoryShardStore<String, u32>, 4, 3> =
+            ShardTree::new(MemoryShardStore::empty(), 100);
+        tree.insert_frontier_nodes(original.clone(), Retention::Ephemeral)
+            .unwrap();
+
+        let frontier = tree.frontier().unwrap().unwrap();
+        assert_eq!(frontier, original);
+    }
+
+    #[test]
+    fn frontier_from_appended_leaves() {
+        // Append leaves with the last one marked, so it isn't pruned away.
+        let mut tree: ShardTree<MemoryShardStore<String, u32>, 4, 3> =
+            ShardTree::new(MemoryShardStore::empty(), 100);
+        for c in 'a'..='i' {
+            tree.append(c.to_string(), Retention::Ephemeral).unwrap();
+        }
+        tree.append("j".to_string(), Retention::Marked).unwrap();
+
+        let frontier = tree.frontier().unwrap().unwrap();
+        // Position 9 = binary 1001: ommers at level 0 ("i") and level 3 ("abcdefgh")
+        assert_eq!(
+            frontier,
+            NonEmptyFrontier::from_parts(
+                Position::from(9),
+                "j".to_string(),
+                vec!["i".to_string(), "abcdefgh".to_string()]
+            )
+            .unwrap()
+        );
+    }
+
+    #[test]
+    fn frontier_roundtrip() {
+        // Build a frontier, insert it, then extract it back.
+        let original = NonEmptyFrontier::from_parts(
+            Position::from(9),
+            "j".to_string(),
+            vec!["i".to_string(), "abcdefgh".to_string()],
+        )
+        .unwrap();
+
+        let mut tree: ShardTree<MemoryShardStore<String, u32>, 4, 3> =
+            ShardTree::new(MemoryShardStore::empty(), 100);
+        tree.insert_frontier_nodes(original.clone(), Retention::Ephemeral)
+            .unwrap();
+
+        let extracted = tree.frontier().unwrap().unwrap();
+        assert_eq!(extracted, original);
+    }
+
     #[test]
     fn checkpoint_pruning_repeated() {
         // Create a tree with some leaves.

shardtree/src/prunable.rs

@@ -1028,9 +1028,13 @@ impl<H: Hashable + Clone + PartialEq> LocatedPrunableTree<H> {
         result
     }
 
-    /// Returns the Merkle frontier of the tree, if the tree is nonempty and has no `Nil` leaves
-    /// prior to the leaf at the greatest position.
-    pub fn frontier(&self) -> Option<NonEmptyFrontier<H>> {
+    /// Returns the position, leaf hash, and ommers for the frontier of this tree,
+    /// or `None` if the frontier cannot be determined.
+    ///
+    /// The returned ommers cover only the levels within this tree (from level 0 up to
+    /// but not including this tree's root level). This is a building block for
+    /// [`ShardTree::frontier`] which extends the ommers to the full tree depth.
+    pub(crate) fn frontier_ommers(&self) -> Option<(Position, H, Vec<H>)> {
         /// Traverses the rightmost path of the tree, collecting the frontier leaf and ommers.
         /// Returns `(position, leaf_hash, ommers)` with ommers ordered from lowest to highest
         /// level, or `None` if the frontier cannot be extracted.
@@ -1073,7 +1077,13 @@ impl<H: Hashable + Clone + PartialEq> LocatedPrunableTree<H> {
             }
         }
 
-        let (position, leaf, ommers) = go(self.root_addr, &self.root)?;
+        go(self.root_addr, &self.root)
+    }
+
+    /// Returns the Merkle frontier of the tree, if the tree is nonempty and has no `Nil` leaves
+    /// prior to the leaf at the greatest position.
+    pub fn frontier(&self) -> Option<NonEmptyFrontier<H>> {
+        let (position, leaf, ommers) = self.frontier_ommers()?;
         NonEmptyFrontier::from_parts(position, leaf, ommers).ok()
     }
 }