format: look a name up in a v1 group down its B-tree, as libhdf5 does

Opening one dataset of a v1 (symbol table) group read every symbol
table node and every name of the group to find it: over openUrl, 74
requests and 193 MB to read one 64 KiB dataset of the reviewer's
3000-dataset h5py file (libver earliest) at 1 MiB blocks, 515 requests
and 34 MB at 64 KiB. Locally it made a lookup O(entries).

`group_v1::find_v1_entry` looks the name up as libhdf5's
`H5G__stab_lookup` does: `H5B_find`'s binary search at each B-tree node
with `H5G__node_cmp3` (left key < name <= right key, keys being names in
the local heap, compared bytewise like strcmp), then the one symbol
table node, after the heap's free list is checked as the listing does.
The heap's data segment (up to 1 MiB) is hinted, since the keys are read
one after another. Path resolution uses it for a v1 group; only when it
does not find a hard link of that name (a soft link, or a B-tree out of
name order, damaged or hand-made, where libhdf5 would report the name
missing) does it read every entry as before. A storage error is returned
as is (over the lazy reader, a miss: reading every entry would not get
further). The result differs from before only in a group holding two
entries of one name, where the B-tree's is now the one found, as in
libhdf5.

Measured with tests/lazy.rs listing_cost_of_a_given_file, open + read
one 64 KiB dataset of the reviewer-like file, passes/requests/bytes,
before -> after (open included):
  earliest, 1 MiB:  7/74/193.6 MB -> 6/5/5.2 MB
  earliest, 64 KiB: 9/515/34.1 MB -> 8/7/524 KB
  latest (dense groups, already a name-index lookup): 1 MiB 8/7/6.7 MB
  -> 7/7/6.7 MB, 64 KiB 9/8/581 KB -> 8/8/581 KB (the previous
  commit's hints: the name index header with the heap header)
New tests, failing before: every child of v1_groups_400.h5 resolves
to its listed address reading under 1/8 of the listing's bytes, and
missing names are not found; a name moved out of B-tree order is still
found (by the fallback); reading one of 2000 datasets lazily at 512-byte
blocks takes at most 7 passes and 6 requests (earliest; 529 requests,
333 kB before) and 8 passes, 9 requests (latest).
Conformance 600 of 697 (baseline 600), no file's class or detail
changed against a run of main.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

crates/clawhdf5-format/src/group_v2.rs

@@ -385,6 +385,27 @@ fn lookup_link<S: Storage + ?Sized>(
     length_size: u8,
 ) -> Result<Option<LinkTarget>, FormatError> {
     if is_v1_group(object_header) {
+        // Down the group's B-tree, as libhdf5 looks a name up; only when
+        // that does not find a hard link of that name is every entry read
+        // (a soft link, a group whose B-tree is out of order). A storage
+        // error (a read a restartable storage has not fetched yet) is
+        // returned as is: reading every entry would not get further.
+        if let Some(sym_msg) = object_header
+            .messages
+            .iter()
+            .find(|m| m.msg_type == MessageType::SymbolTable)
+        {
+            let stm = SymbolTableMessage::parse(&sym_msg.data, offset_size)?;
+            match group_v1::find_v1_entry(file_data, &stm, name, offset_size, length_size) {
+                Ok(Some(e)) if e.object_header_address != u64::MAX => {
+                    return Ok(Some(LinkTarget::Hard {
+                        object_header_address: e.object_header_address,
+                    }));
+                }
+                Err(e @ FormatError::Storage(_)) => return Err(e),
+                _ => {}
+            }
+        }
         let entries = resolve_group_entries(file_data, object_header, offset_size, length_size)?;
         if let Some(e) = entries
             .iter()
@@ -984,6 +1005,86 @@ mod tests {
         assert_eq!(values, vec![22.5, 23.1, 21.8]);
     }
 
+    /// `v1_groups_400.h5` from its superblock on (it has a user block).
+    fn v1_groups_400() -> (Vec<u8>, Superblock) {
+        let all: &[u8] = include_bytes!("../tests/fixtures/v1_groups_400.h5");
+        let data = all[signature::find_signature(all).unwrap()..].to_vec();
+        let sb = Superblock::parse(&data, 0).unwrap();
+        (data, sb)
+    }
+
+    /// Every child of a v1 group resolves by name, down the group's B-tree,
+    /// to the address the listing gives, reading a small part of what the
+    /// listing reads; a name the group does not hold is not found.
+    #[test]
+    fn v1_lookup_down_the_btree_agrees_with_the_listing() {
+        let (data, sb) = v1_groups_400();
+        let children = resolve_group_children(&data, &sb, sb.root_group_address).unwrap();
+        assert_eq!(children.len(), 401);
+        for c in &children {
+            let path = format!("/{}", c.name);
+            assert_eq!(
+                resolve_path_any(&data, &sb, &path).unwrap(),
+                c.object_header_address,
+                "{path}"
+            );
+        }
+        for missing in ["/g0400", "/a", "/g", "/g00000", "/zz", "/x0"] {
+            assert!(
+                matches!(
+                    resolve_path_any(&data, &sb, missing),
+                    Err(FormatError::PathNotFound(_))
+                ),
+                "{missing}"
+            );
+        }
+        let st = crate::storage::CountingStorage::new(data.clone());
+        resolve_group_children_in(&st, &sb, sb.root_group_address).unwrap();
+        let listing = st.bytes_read();
+        st.reset();
+        let last = children.last().unwrap();
+        assert_eq!(
+            resolve_path_any_in(&st, &sb, &format!("/{}", last.name)).unwrap(),
+            last.object_header_address
+        );
+        assert!(
+            st.bytes_read() * 8 < listing,
+            "lookup read {} bytes, listing {listing}",
+            st.bytes_read()
+        );
+    }
+
+    /// A v1 group whose B-tree is out of name order (a name changed in the
+    /// heap so that it sorts past every key) is still looked up by reading
+    /// every entry, as before the lookup went down the B-tree.
+    #[test]
+    fn v1_lookup_falls_back_when_the_btree_is_out_of_order() {
+        let (mut data, sb) = v1_groups_400();
+        let at: Vec<usize> = data
+            .windows(6)
+            .enumerate()
+            .filter(|(_, w)| *w == b"g0200\0")
+            .map(|(i, _)| i)
+            .collect();
+        assert_eq!(at.len(), 1, "one heap string");
+        data[at[0]] = b'~';
+        let children = resolve_group_children(&data, &sb, sb.root_group_address).unwrap();
+        let moved = children.iter().find(|c| c.name == "~0200").unwrap();
+        assert_eq!(
+            resolve_path_any(&data, &sb, "/~0200").unwrap(),
+            moved.object_header_address
+        );
+        assert!(resolve_path_any(&data, &sb, "/g0200").is_err());
+        for c in &children {
+            let path = format!("/{}", c.name);
+            assert_eq!(
+                resolve_path_any(&data, &sb, &path).unwrap(),
+                c.object_header_address,
+                "{path}"
+            );
+        }
+    }
+
     #[test]
     fn path_not_found_v2() {
         let file_data: &[u8] = include_bytes!("../tests/fixtures/v2_groups.h5");