expose the zagg-pyramid/2 fixed ladder as a multiscale / datatree view

[espg]

🤖 from Claude (filed at espg's direction, 2026-08-05; companion to the /2 heads-up on issue #1)

Motivation

Once zagg-pyramid/2 lands (englacial/zagg#389; design record englacial/zagg#381), every /2 store is inherently multiresolution: a guaranteed ladder at every HEALPix order from 0 through the base (two numbers — parent_order and d — determine the whole above-shard geometry), recorded fully expanded in block-level pyramid.overviews. Today the reader surface is per-level opens; the store's actual identity wants a resolution-aware view.

Scope

• open_hive (or a sibling entry point) returns a multiscale view: a datatree with one dataset per order, or a resolution= selector — decode the expanded manifest list verbatim, never derive.
• Surface the per-entry provenance as level metadata once the staged sweep lands it (fold regime, source_children, merges-from-raw — pyramid v2: staged dense sweep on the partition machinery englacial/zagg#384), so users can filter levels by generation.
• Honor the upgraded accuracy doctrine in the API docs: exact-class fields are exactly correct at every order (true downsampling pyramid); approximate-class fields are analysis-grade at their recorded generation — not display-only.
• Zoom-out ergonomics: the ladder roots at order 0 for every store (≤ 12 root artifacts world-view), which is the natural default level for a first render (relevant to the issue Percentile-surface materialization: dense (quantile, cells) views for the gridlook feeder #21 gridlook feeder).

Notes

• xdggs wrinkle, recorded from prior work: upstream xdggs forbids cross-resolution alignment in one index — the fixed ladder makes cross-resolution relationships well-defined within this package, so the exposure route is our own view/convention, not an upstream PR.
• A zagg-side counterpart (declare the multiresolution ladder in machine-readable convention metadata (zarr multiscales + DGGS refinement) englacial/zagg#392) will declare the ladder in machine-readable convention attrs (multiscales flavor TBD there); this reader should consume the manifest first and treat the convention attrs as the discovery mirror.
• Sequencing: after the /2 repin + conformance pass suggested on issue Plan: moczarr — sparse-DGGS xarray reader for morton-hive stores #1.

Refs issue #1 (plan), #21 (percentile-surface feeder), #31 (all-time surface — unaffected in posture, stays in the family dict).

[espg]

🤖 from Claude

Gating note: the data-model decision for this exposure now lives in issue #37 (DataTree vs resolution dimension vs custom multi-res index, cross-resolution operation policy, index design). Implementation here follows that written decision.