feature, add token-based object identity (H5O_token_t + H5Oget_info3)

[steven-varga]

Summary

Add the HDF5 1.12 token-based object identity layer — H5O_token_t and H5Oget_info3 — on top of the path-based traversal helpers that already ship. This is what lets callers identify, compare, and persist a reference to an HDF5 object independent of its path (so a hard-link rename doesn't break identity).

What already shipped (v1.12.6 — via #270)

The path-based traversal half of the original scope landed and #270 was closed:

• h5::ls(fd, path) — single-level listing via H5Literate.
• h5::dfs(fd, path) — recursive depth-first listing via H5Lvisit.
• h5::bfs(fd, path) — recursive breadth-first listing (stable-sort over dfs output by depth).
• All live in h5cpp/H5Ialgorithm.hpp. Return std::vector<std::string> of paths relative to directory.

What's still pending — and why it's nontrivial

The traversal surface above is path-based: each entry is a string. The 1.12 surface that's missing identifies objects via opaque tokens, which are stable across symlink resolution and hard-link rename, and which the C API uses for the new H5Oget_info3 family.

Two real concerns:

1. H5Oget_info3 portability. The function was renamed in HDF5 1.12.3 (the prior H5Oget_info2 is only visible when HDF5_ENABLE_DEPRECATED_SYMBOLS=ON, which the project's pinned source-build disables). Earlier in v1.12.6 work the function was deliberately removed from H5cout.hpp after a 1.12.2 vs 1.12.3 ABI mismatch tripped CI. Any token-based API needs to either:
   • gate on H5_VERSION_GE(1,12,3) and provide a H5Oget_info2 fallback for 1.12.0–1.12.2, or
   • bump the HDF5 floor to 1.12.3 in H5CPP_HDF5_FLOOR (currently 1.10.4) — which the CI matrix already supplies.
2. Token opacity. H5O_token_t is a fixed-size opaque blob (uint8_t[H5O_MAX_TOKEN_SIZE]). Equality is per-file (H5Otoken_cmp), not memcmp. Persisting a token across program runs requires H5Otoken_to_str / H5Otoken_from_str.

HDF5 APIs to wrap

• H5Oget_info3 — typed H5O_info2_t (with embedded H5O_token_t)
• H5Oget_info_by_name3, H5Oget_info_by_idx3
• H5Otoken_cmp — per-file token equality
• H5Otoken_to_str, H5Otoken_from_str — persistence

Proposed h5cpp API

// Cheap object metadata — type, refcount, atime/mtime, token.
h5::object_info_t info = h5::oinfo(fd, "/sensors/imu");

// Identity that survives rename.
h5::token_t tok = info.token;            // opaque, file-scoped
bool same     = h5::token_equal(fd, tok, other_tok);

// Persist + restore (e.g. via attribute).
std::string s = h5::to_string(fd, tok);  // hex / ASCII
h5::token_t back = h5::token_from_string(fd, s);

// Token-based ls (returns tokens alongside paths).
auto entries = h5::ls_tokens(fd, "/");   // vector<pair<string, token_t>>

Acceptance criteria

• h5::object_info_t descriptor mirroring H5O_info2_t with an embedded h5::token_t
• h5::oinfo(loc, path) backed by H5Oget_info_by_name3 (with 1.12.0–1.12.2 fallback OR an explicit floor bump)
• h5::token_equal(loc, a, b) via H5Otoken_cmp (per-file equality, not memcmp)
• h5::to_string(loc, token) / h5::token_from_string(loc, str) round-trip via H5Otoken_to_str / H5Otoken_from_str
• h5::ls_tokens / h5::dfs_tokens variants pairing paths with tokens (or a single h5::walk that returns info_t records)
• Tests covering: token equality across renames, persistence round-trip, ABI gate against the chosen HDF5 floor
• Decision recorded (commit msg or README): keep the dual-API gate on 1.12.0–1.12.2 OR bump H5CPP_HDF5_FLOOR to 1.12.3

Out of scope (covered elsewhere)

• Path-based traversal (h5::ls / dfs / bfs) — done in feature, add link creation and traversal APIs #270.
• H5Lvisit / H5Literate callback wrapping — done in feature, add link creation and traversal APIs #270.