refactor, deprecate legacy dt_t compound type engine once compiler plugin emits compiler_meta_t

[steven-varga]

Summary

The old HDF5 compound type engine — h5::dt_t / h5::register_struct() /
H5CPP_REGISTER_STRUCT — should be deprecated (not removed) once the updated
compiler plugin (vargalabs/h5cpp-compiler#9) generates compiler_meta_t +
is_reflected_compound_t specializations instead.

Rationale for deprecation over removal: Three legitimate user populations cannot
or will not use the compiler plugin: cross-compilation targets, MSVC-only shops, and
users with hand-crafted dt_t specializations for third-party or ABI-stable types.
The resolved_type_t<T> fallback branch (introduced in #89) is a zero-cost
if constexpr dead branch for new-engine types — keeping it has no runtime overhead
and preserves a valid migration path.

Background

Issue #87 introduced the new type engine (storage_traits_t::create_type()) in
H5Tmeta.hpp. Issue #89 wired it into the I/O path via resolved_type_t<T>, which
prefers the new engine but falls back to h5::dt_t for types not yet migrated.
That fallback should remain permanently as a compatibility opt-out, not be removed.

What must stay (never remove)

• H5CPP_REGISTER_TYPE_ macro and dt_t<T> specializations for primitive types
  (int, float, etc.) — the new engine calls H5T_NATIVE_* handles which are still
  registered via this path.
• The else branch in resolved_type_t<T>::resolved_type_t() — zero cost, enables
  opt-out for users without the compiler plugin.

Work

• Mark H5CPP_REGISTER_STRUCT with a deprecation notice (comment + docs); keep the macro
• Mark h5::register_struct() with [[deprecated]]; keep the declaration and default body
• Update documentation to direct new users to the compiler plugin path
• Do not remove dt_t<T> fallback from resolved_type_t (it is permanent compat shim)
• Do not remove H5CPP_REGISTER_TYPE_ or primitive dt_t specializations
• Verify all existing tests remain green; add a test confirming the fallback path still
  works for a hand-registered type (no compiler plugin)

Preconditions — all three must be met before this issue can be worked

1. build, update code generator to emit compiler_meta_t<T> for new h5cpp type engine h5cpp-compiler#9 merged — plugin emits compiler_meta_t output
2. refactor, dataset create/read/write to consume the new type engine #89 merged — new engine is wired into the I/O path with the fallback in place
3. refactor, apply minimal downstream updates to property/reference/file layers #92 merged — downstream property/reference/file layers consume the new engine

Depends on

• refactor, dataset create/read/write to consume the new type engine #89 (I/O path wiring with fallback)
• refactor, apply minimal downstream updates to property/reference/file layers #92 (downstream layer updates)
• build, update code generator to emit compiler_meta_t<T> for new h5cpp type engine h5cpp-compiler#9 (plugin update — external repo)

[steven-varga]

Status assessment (2026-05-14)

Blocked on all three stated preconditions — none have merged yet:

Precondition	Status
#89 — new type engine wired into I/O path	open
#92 — downstream property/reference/file layers updated	open
vargalabs/h5cpp-compiler#9 — plugin emits compiler_meta_t output	open

A worktree exists (120-remove-legacy-dt-t-type-engine) but the branch carries no commits ahead of release — correctly held dormant.

Key clarification on scope: This is a deprecation, not a removal. dt_t<T> fallback in resolved_type_t<T>, H5CPP_REGISTER_TYPE_, and primitive type specializations are permanent and must not be touched. Only H5CPP_REGISTER_STRUCT and h5::register_struct() get the deprecation notice.

Recommended sequencing: #89 → #92 in parallel once #89 lands, then h5cpp-compiler#9, then this issue. Attempting any earlier risks writing deprecation notices against an API surface that is still moving.

No action needed until the three blockers clear.