moczarr.surfaces

Percentile-surface materialization + the resolution ladder (issue #21).

The gridlook feeder: the ratified viewer posture (englacial/zagg#265, espg/gridlook#1) is that the browser never decodes digest bytes — dense materialization happens hub-side, and percentile surfaces carry a quantile DIMENSION so the viewer's existing dimension slider drives bare-earth↔canopy browsing with zero frontend changes. This module is that hub-side step, plus the ladder metadata the gridlook#10 order picker enumerates (declared orders, materialized orders, per-order resolution).

Two surfaces:

• :func:quantile_surface / :func:open_surface — evaluate a stored t-digest field into a dense (quantile, cells) float array over one level's cells, the morton coordinate carried, the caller's fill (default NaN) where a cell holds no digest. Exact/dense fields (a count choropleth) ride along un-evaluated via carry=, or alone via field=None. Strata-aware: a sequence of digest fields is merged per cell before evaluation (one deterministic concatenate-and-sort — the lossless t-digest union, no re-compression), so a h_tdigest_signal/h_tdigest_noise store answers per-stratum or merged-total surfaces by argument — and by argument ONLY: the sort key is (mean, weight), so naming the strata the other way round is the same surface even when they share a centroid mean.
• :func:read_ladder — the picker contract: one typed record per level of :func:moczarr.level.pyramid_levels' table, extended with the per-order ground resolution (mortie.order2res) and a probed materialized answer (overview presence via :func:moczarr.pyramid.read_pyramid, column presence via the §4.6 columns' own groups maps — declared ≠ materialized is the live-store failure mode the picker must not trip on).

The t-digest algebra is moczarr's own (:mod:moczarr.tdigest, pure numpy; issue #64 — no reader function needs zagg, whose kernels are the PARITY arm only, under the demoted moczarr[zagg] extra), and evaluation honours the standing trap: every digest — merged concatenation or single stored cell — is ordered by (mean, weight) before the kernel sees it, because the interp-based kernel assumes mean order AND its cumulative-weight walk is sensitive to the order of centroids that share a mean. Native surfaces only (the englacial/zagg#550 ruling): no moczarr.dggs, no xdggs, no decode=.

Ladder dataclass

A store's resolution ladder, typed — the gridlook#10 picker contract.

levels is the whole declared table, finest first; the two projections answer the picker's questions directly: declared — every addressable cell order — and materialized — the subset with stamped artifacts today (an order declared but not materialized never becomes a catalog entry). Per-order resolution rides each :class:LadderLevel.

Source code in src/moczarr/surfaces.py

@dataclass(frozen=True)
class Ladder:
    """A store's resolution ladder, typed — the gridlook#10 picker contract.

    ``levels`` is the whole declared table, finest first; the two
    projections answer the picker's questions directly: ``declared`` — every
    addressable cell order — and ``materialized`` — the subset with stamped
    artifacts today (an order declared but not materialized never becomes a
    catalog entry). Per-order resolution rides each :class:`LadderLevel`.
    """

    levels: tuple[LadderLevel, ...]

    @property
    def declared(self) -> tuple[int, ...]:
        """Every declared cell order, finest first."""
        return tuple(lvl.cell_order for lvl in self.levels)

    @property
    def materialized(self) -> tuple[int, ...]:
        """The declared cell orders with stamped artifacts today (probed)."""
        return tuple(lvl.cell_order for lvl in self.levels if lvl.materialized)

declared property

Every declared cell order, finest first.

materialized property

The declared cell orders with stamped artifacts today (probed).

LadderLevel dataclass

One resolution level of the picker's ladder (:func:read_ladder).

Attributes:

Name	Type	Description
cell_order	int	The level's resolution — the cell order a reader picks (:func:moczarr.level.pyramid_levels' key, and :func:moczarr.level.open_level / :func:open_surface's address).
order	int	The hive-tree node order whose artifact carries the level.
artifact	str	"source" | "column" | "overview" — the level table's vocabulary.
resolution_km	float	Approximate ground scale of one cell at cell_order (mortie.order2res: the RMS cell spacing on the equal-area HEALPix sphere), so catalog labels and camera→order mappings are derived, never hardcoded.
materialized	bool or None	Whether the level has stamped artifacts on disk today: True for the source level of an unwindowed store (the leaves ARE the store), probed for overview and column levels — and for the source level too once a windowed store is read at a NAMED window, whose leaves are per window ({shard}_{window}.zarr, D23) and exist only for the windows that were swept. None when unprobed (probe=False) or unprobeable (no usable root coverage; a grouped tree's overview nodes; an overview rung whose /2 node declares SEVERAL cell orders, which the node-existence probe cannot tell apart). Declared ≠ materialized is a legal recorded state — the picker lists True levels only.
presence	OrderPresence or None	The probe counts behind materialized, when probed: for an overview level the D4 existence probe (:func:moczarr.pyramid. read_pyramid's numbers for its node order); for a column level nodes counts the candidate leaves and stamped the admitted columns whose own groups map carries this resolution (classification-bound, unlike the overview probe — a column's membership lives only in its attrs); for a windowed store's probed source level nodes counts the candidate leaves and stamped the ones stamped for that window. None on an unprobed level and on an unwindowed store's source level, which is not probed.

Source code in src/moczarr/surfaces.py

@dataclass(frozen=True)
class LadderLevel:
    """One resolution level of the picker's ladder (:func:`read_ladder`).

    Attributes
    ----------
    cell_order : int
        The level's resolution — the cell order a reader picks
        (:func:`moczarr.level.pyramid_levels`' key, and
        :func:`moczarr.level.open_level` / :func:`open_surface`'s address).
    order : int
        The hive-tree node order whose artifact carries the level.
    artifact : str
        ``"source"`` | ``"column"`` | ``"overview"`` — the level table's
        vocabulary.
    resolution_km : float
        Approximate ground scale of one cell at ``cell_order``
        (``mortie.order2res``: the RMS cell spacing on the equal-area
        HEALPix sphere), so catalog labels and camera→order mappings are
        derived, never hardcoded.
    materialized : bool or None
        Whether the level has stamped artifacts on disk today: ``True`` for
        the source level of an unwindowed store (the leaves ARE the store),
        probed for overview and column levels — and for the source level
        too once a windowed store is read at a NAMED window, whose leaves
        are per window (``{shard}_{window}.zarr``, D23) and exist only for
        the windows that were swept. ``None`` when unprobed
        (``probe=False``) or unprobeable (no usable root coverage; a
        grouped tree's overview nodes; an overview rung whose ``/2`` node
        declares SEVERAL cell orders, which the node-existence probe cannot
        tell apart). Declared ≠ materialized is a legal recorded state —
        the picker lists ``True`` levels only.
    presence : OrderPresence or None
        The probe counts behind ``materialized``, when probed: for an
        overview level the D4 existence probe (:func:`moczarr.pyramid.
        read_pyramid`'s numbers for its node order); for a column level
        ``nodes`` counts the candidate leaves and ``stamped`` the admitted
        columns whose own ``groups`` map carries this resolution
        (classification-bound, unlike the overview probe — a column's
        membership lives only in its attrs); for a windowed store's probed
        source level ``nodes`` counts the candidate leaves and ``stamped``
        the ones stamped for that window. ``None`` on an unprobed level and
        on an unwindowed store's source level, which is not probed.
    """

    cell_order: int
    order: int
    artifact: str
    resolution_km: float
    materialized: bool | None
    presence: OrderPresence | None = None

open_surface(store_root, cell_order, field, *, quantiles=DEFAULT_QUANTILES, fill=np.nan, carry=(), name=None, product=None, manifest=None, aoi=None, window=None, all_time=False, anonymous=False, fabricate_cell_ids='auto', index_kind='moc', concurrency=32, xr_kwargs=None, store=None, **store_kwargs)

Open one level and materialize its surface — the one-call feeder.

:func:moczarr.level.open_level then :func:quantile_surface, with open_level's whole signature threaded through verbatim (defaults unchanged): aoi scopes rows exactly as the level model does (an out-of-coverage AOI yields the schema-correct EMPTY surface, (len(quantiles), 0)), window follows the D23 dialect (required on a windowed store, refused on an unwindowed one, the reserved all-time token refused everywhere), all_time reads a windowed store's §4.5 cross-window folds (overview levels only), fabricate_cell_ids governs whether the surface carries a cell_ids coordinate at all, index_kind selects the level's index (and with it how aoi cuts rows), and xr_kwargs reaches xr.open_zarr — the knob that governs the read, which is the wall at viewer scales. None — with the arm's own warning — when the level is declared but unmaterialized, exactly as open_level answers. Surface arguments (quantiles/fill/carry/name, field string / sequence / None) follow :func:quantile_surface.

Source code in src/moczarr/surfaces.py

def open_surface(
    store_root: str,
    cell_order: int,
    field,
    *,
    quantiles=DEFAULT_QUANTILES,
    fill: float = np.nan,
    carry=(),
    name: str | None = None,
    product: str | None = None,
    manifest: dict | None = None,
    aoi=None,
    window: str | None = None,
    all_time: bool = False,
    anonymous: bool = False,
    fabricate_cell_ids: bool | str = "auto",
    index_kind: str = "moc",
    concurrency: int | None = 32,
    xr_kwargs: dict[str, Any] | None = None,
    store: Any = None,
    **store_kwargs: Any,
):
    """Open one level and materialize its surface — the one-call feeder.

    :func:`moczarr.level.open_level` then :func:`quantile_surface`, with
    ``open_level``'s whole signature threaded through verbatim (defaults
    unchanged): ``aoi`` scopes rows exactly as the level model does (an
    out-of-coverage AOI yields the schema-correct EMPTY surface,
    ``(len(quantiles), 0)``), ``window`` follows the D23 dialect (required
    on a windowed store, refused on an unwindowed one, the reserved
    all-time token refused everywhere), ``all_time`` reads a windowed
    store's §4.5 cross-window folds (overview levels only),
    ``fabricate_cell_ids`` governs whether the surface carries a
    ``cell_ids`` coordinate at all, ``index_kind`` selects the level's
    index (and with it how ``aoi`` cuts rows), and ``xr_kwargs`` reaches
    ``xr.open_zarr`` — the knob that governs the read, which is the wall at
    viewer scales. ``None`` — with the arm's own warning — when the level
    is declared but unmaterialized, exactly as ``open_level`` answers.
    Surface arguments (``quantiles``/``fill``/``carry``/``name``, ``field``
    string / sequence / ``None``) follow :func:`quantile_surface`.
    """
    ds = open_level(
        store_root,
        cell_order,
        product=product,
        manifest=manifest,
        aoi=aoi,
        window=window,
        all_time=all_time,
        anonymous=anonymous,
        fabricate_cell_ids=fabricate_cell_ids,
        index_kind=index_kind,
        concurrency=concurrency,
        xr_kwargs=xr_kwargs,
        store=store,
        **store_kwargs,
    )
    if ds is None:
        return None
    return quantile_surface(ds, field, quantiles, fill=fill, carry=carry, name=name)

quantile_surface(ds, field, quantiles=DEFAULT_QUANTILES, *, fill=np.nan, carry=(), name=None)

One level's digest field, dense: a (quantile, cells) Dataset.

Takes any Dataset of the issue-#37 level model (:func:moczarr.level. open_level, :func:moczarr.open.open_hive, :func:moczarr.pyramid. open_overview_order, :func:moczarr.level.open_column_order — the shape is the model's one law) and evaluates field's stored t-digests per cell at quantiles, returning a NEW dense Dataset:

• field as a float64 (quantile, cells) variable — quantile a real dimension with the requested values as its coordinate, so the output opens in vanilla xarray and a viewer's dimension slider drives it directly;
• the morton (and cell_ids, when present) coordinate carried as PLAIN arrays — materialization is dense by design, laziness ends here;
• fill (default NaN) where a cell holds no digest (an absent/empty vlen cell, or every stratum empty);
• carry names dense (exact-class) variables copied verbatim onto the cells axis — a count choropleth needs no evaluation. One name, a sequence of them, or any iterable (consumed once, like field: a bare string is ONE name, never its characters);
• the level's morton_hive / zagg_level / zagg_objects attrs carried forward, plus :data:SURFACE_ATTR on the evaluated variable recording fields/quantiles/fill — the last as a number, or as the quoted token name ("NaN"/"Infinity"/ "-Infinity") when it is not finite, so the written zarr.json stays strict JSON for a browser reader (:func:_json_fill).

field is one digest variable name, a sequence of them (the strata arm: the cells' centroid sets are merged by the lossless concatenate-and-sort union before evaluation — the merged TOTAL of ("h_tdigest_signal", "h_tdigest_noise"), identical to the flipped pair's, ties included; per-stratum surfaces are one call per field), or None with a non-empty carry (the dense-only arm: no evaluation, no quantile dimension). The default merged name is the fields' common prefix (h_tdigest); name= overrides. Evaluation calls :func:moczarr.tdigest.quantile_from_tdigest per cell — the values are exactly that kernel's, per cell, by construction (the issue #21 acceptance), and that kernel is pinned value-exact against zagg's by the parity gate (issue #64).

Source code in src/moczarr/surfaces.py

def quantile_surface(
    ds,
    field,
    quantiles=DEFAULT_QUANTILES,
    *,
    fill: float = np.nan,
    carry=(),
    name: str | None = None,
):
    """One level's digest field, dense: a ``(quantile, cells)`` Dataset.

    Takes any Dataset of the issue-#37 level model (:func:`moczarr.level.
    open_level`, :func:`moczarr.open.open_hive`, :func:`moczarr.pyramid.
    open_overview_order`, :func:`moczarr.level.open_column_order` — the
    shape is the model's one law) and evaluates ``field``'s stored
    t-digests per cell at ``quantiles``, returning a NEW dense Dataset:

    - ``field`` as a float64 ``(quantile, cells)`` variable — ``quantile``
      a real dimension with the requested values as its coordinate, so the
      output opens in vanilla xarray and a viewer's dimension slider drives
      it directly;
    - the ``morton`` (and ``cell_ids``, when present) coordinate carried as
      PLAIN arrays — materialization is dense by design, laziness ends
      here;
    - ``fill`` (default NaN) where a cell holds no digest (an absent/empty
      vlen cell, or every stratum empty);
    - ``carry`` names dense (exact-class) variables copied verbatim onto
      the ``cells`` axis — a count choropleth needs no evaluation. One
      name, a sequence of them, or any iterable (consumed once, like
      ``field``: a bare string is ONE name, never its characters);
    - the level's ``morton_hive`` / ``zagg_level`` / ``zagg_objects`` attrs
      carried forward, plus :data:`SURFACE_ATTR` on the evaluated variable
      recording ``fields``/``quantiles``/``fill`` — the last as a number,
      or as the quoted token name (``"NaN"``/``"Infinity"``/
      ``"-Infinity"``) when it is not finite, so the written ``zarr.json``
      stays strict JSON for a browser reader (:func:`_json_fill`).

    ``field`` is one digest variable name, a sequence of them (the strata
    arm: the cells' centroid sets are merged by the lossless
    concatenate-and-sort union before evaluation — the merged TOTAL of
    ``("h_tdigest_signal", "h_tdigest_noise")``, identical to the flipped
    pair's, ties included; per-stratum surfaces are
    one call per field), or ``None`` with a non-empty ``carry`` (the
    dense-only arm: no evaluation, no ``quantile`` dimension). The default
    merged name is the fields' common prefix (``h_tdigest``); ``name=``
    overrides. Evaluation calls :func:`moczarr.tdigest.quantile_from_tdigest`
    per cell — the values are exactly that kernel's, per cell, by
    construction (the issue #21 acceptance), and that kernel is pinned
    value-exact against zagg's by the parity gate (issue #64).
    """
    import xarray as xr

    fields: tuple[str, ...]
    if field is None:
        fields = ()
    elif isinstance(field, str):
        fields = (field,)
    else:
        fields = tuple(field)
        if not fields:
            raise ValueError("field=[] names no digest field; pass a name, a sequence, or None")
    # Normalized ONCE, beside field's: a bare string is one name (not its
    # characters), and a one-shot iterable must survive both the probe below
    # and the carry loop at the bottom.
    carry = (carry,) if isinstance(carry, str) else tuple(carry)
    if not fields and not carry:
        raise ValueError(
            "field=None materializes no digests, so carry= must name at least one "
            "dense field (the count/exact arm)"
        )

    dim = "cells"
    probe = fields[0] if fields else carry[0]
    if probe in ds:
        dims = ds[probe].dims
        if len(dims) != 1:
            raise ValueError(
                f"field {probe!r} has dims {dims}, expected one cells axis: surfaces "
                f"are per-level (one resolution, one 1-D cell domain)"
            )
        dim = dims[0]
    n = int(ds.sizes.get(dim, 0))

    data_vars: dict[str, Any] = {}
    coords: dict[str, Any] = {}
    if fields:
        from moczarr.ragged import parse_ragged_attrs
        from moczarr.tdigest import quantile_from_tdigest

        qs = np.atleast_1d(np.asarray(quantiles, dtype=np.float64))
        if qs.ndim != 1 or qs.size == 0:
            raise ValueError(f"quantiles={quantiles!r}: expected a non-empty 1-D sequence")
        if not np.all(np.isfinite(qs)) or qs.min() < 0.0 or qs.max() > 1.0:
            raise ValueError(f"quantiles={quantiles!r}: every quantile must lie in [0, 1]")
        columns = _digest_columns(ds, fields, dim)
        elements = [parse_ragged_attrs(ds[f].attrs, field=f) for f in fields]
        out = np.full((qs.size, n), np.float64(fill), dtype=np.float64)
        for j in range(n):
            digest = _cell_digest(columns, elements, j)
            if digest is None:
                continue
            for i in range(qs.size):
                out[i, j] = quantile_from_tdigest(digest, float(qs[i]))
        out_name = _surface_name(fields, name)
        data_vars[out_name] = xr.DataArray(
            out,
            dims=("quantile", dim),
            attrs={
                SURFACE_ATTR: {
                    "fields": list(fields),
                    "quantiles": qs.tolist(),
                    "fill": _json_fill(fill),
                }
            },
        )
        coords["quantile"] = qs

    for cname in carry:
        if cname not in ds:
            raise KeyError(
                f"carry field {cname!r} is not a variable of this level (variables: "
                f"{sorted(ds.data_vars)})"
            )
        var = ds[cname]
        if var.dtype == object:
            raise ValueError(
                f"carry field {cname!r} is an encoded ragged digest: carry= copies "
                f"dense fields verbatim — evaluate a digest by naming it in field="
            )
        if var.dims != (dim,):
            raise ValueError(
                f"carry field {cname!r} has dims {var.dims}, expected ({dim!r},): every "
                f"surfaced field must ride the level's cells axis"
            )
        data_vars[cname] = xr.DataArray(np.asarray(var.values), dims=(dim,), attrs=dict(var.attrs))

    for coord in ("morton", "cell_ids"):
        if coord in ds.coords:
            coords[coord] = (dim, np.asarray(ds[coord].values))
    attrs = {k: ds.attrs[k] for k in _CARRIED_ATTRS if k in ds.attrs}
    return xr.Dataset(data_vars, coords=coords, attrs=attrs)

read_ladder(store_root, *, product=None, manifest=None, window=None, probe=True, anonymous=False, concurrency=32, store=None, **store_kwargs)

A store's resolution ladder as one typed record — the picker feeder.

The gridlook#10 Phase-3 contract in one call: declared orders (the level table, both grammars — a declared-off pyramid is the one-level ladder), materialized orders (probed: which declared levels have stamped artifacts on disk today — declared ≠ materialized is the live-store failure mode a picker must not trip on), and per-order resolution (mortie.order2res at each cell order). Mostly a projection of :func:moczarr.level.pyramid_levels + :func:moczarr.pyramid.read_pyramid, typed per the :class:~moczarr.pyramid.PyramidInfo posture.

materialized per artifact kind: overview levels take :func:moczarr.pyramid.read_pyramid's D4 existence probe (stamped > 0 — existence, not readability, its documented split) — except where a /2 node declares SEVERAL cell orders, whose rungs read None: the node's object carries a scalar zagg_overview.cell_order, so at most one of those rungs is backed and a node-existence count cannot say which; column levels are probed from the §4.6 columns' own groups maps (one batched GET per candidate leaf, shared across the column levels — see :func:_leaf_presence), since the manifest MAY lag the fleet there. The source level is True by definition on an unwindowed store (the leaves ARE the store) and is PROBED on a windowed one whenever a window is named: those leaves are per window ({shard}_{window}.zarr — D23) and exist only for the windows that were swept, so a syntactically valid label that was never swept must read False, not True. It rides the same batched leaf-tier read as the columns, so the extra honesty costs no extra round trip when a column level is probed too — and on a windowed store with no column levels it is the one leaf-tier batch the ladder pays (probe=False opts out entirely). The probe never raises: a malformed or mis-stamped column is warned about and counted as not carrying, so one bad object cannot take the picker's whole catalog entry — the source and overview rungs included — down with it. None marks unknown: probe=False (declaration only — one manifest GET, no coverage or stamp reads, so a windowed store's source rung reads unknown rather than guessing at a named window), an unusable root coverage, or the grouped-tree overview refusal — :attr:Ladder.materialized lists True levels only, so an unknown level never masquerades as materialized.

window follows the shared seam: probing a windowed (morton-hive/2) store requires window=... (its artifacts are per window — D23), an unwindowed store refuses the argument, and the reserved all-time token is refused everywhere. The windowed store's §4.5 all-time fold tier is NOT probed here (its levels are the same cell orders; open them with all_time=True). product re-roots on a D19 multi-product subtree; manifest/store thread an already-read manifest and handle, per the issue-#5 posture.

Source code in src/moczarr/surfaces.py

def read_ladder(
    store_root: str,
    *,
    product: str | None = None,
    manifest: dict | None = None,
    window: str | None = None,
    probe: bool = True,
    anonymous: bool = False,
    concurrency: int | None = 32,
    store: Any = None,
    **store_kwargs: Any,
) -> Ladder:
    """A store's resolution ladder as one typed record — the picker feeder.

    The gridlook#10 Phase-3 contract in one call: **declared orders** (the
    level table, both grammars — a declared-off pyramid is the one-level
    ladder), **materialized orders** (probed: which declared levels have
    stamped artifacts on disk today — declared ≠ materialized is the
    live-store failure mode a picker must not trip on), and **per-order
    resolution** (``mortie.order2res`` at each cell order). Mostly a
    projection of :func:`moczarr.level.pyramid_levels` +
    :func:`moczarr.pyramid.read_pyramid`, typed per the
    :class:`~moczarr.pyramid.PyramidInfo` posture.

    ``materialized`` per artifact kind: overview levels take
    :func:`moczarr.pyramid.read_pyramid`'s D4 existence probe (``stamped >
    0`` — existence, not readability, its documented split) — except where
    a ``/2`` node declares SEVERAL cell orders, whose rungs read ``None``:
    the node's object carries a scalar ``zagg_overview.cell_order``, so at
    most one of those rungs is backed and a node-existence count cannot say
    which; column levels
    are probed from the §4.6 columns' own ``groups`` maps (one batched GET
    per candidate leaf, shared across the column levels — see
    :func:`_leaf_presence`), since the manifest MAY lag the fleet there.
    The **source** level is ``True`` by definition on an unwindowed store
    (the leaves ARE the store) and is PROBED on a windowed one whenever a
    window is named: those leaves are per window (``{shard}_{window}.zarr``
    — D23) and exist only for the windows that were swept, so a
    syntactically valid label that was never swept must read ``False``, not
    ``True``. It rides the same batched leaf-tier read as the columns, so
    the extra honesty costs no extra round trip when a column level is
    probed too — and on a windowed store with no column levels it is the
    one leaf-tier batch the ladder pays (``probe=False`` opts out
    entirely). The probe never raises: a malformed or mis-stamped column is
    warned about and counted as not carrying, so one bad object cannot take
    the picker's whole catalog entry — the source and overview rungs
    included — down with it. ``None`` marks *unknown*: ``probe=False``
    (declaration only — one manifest GET, no coverage or stamp reads, so a
    windowed store's source rung reads unknown rather than guessing at a
    named window), an unusable root coverage, or the grouped-tree overview
    refusal — :attr:`Ladder.materialized` lists ``True`` levels only, so an
    unknown level never masquerades as materialized.

    ``window`` follows the shared seam: probing a windowed
    (``morton-hive/2``) store requires ``window=...`` (its artifacts are
    per window — D23), an unwindowed store refuses the argument, and the
    reserved all-time token is refused everywhere. The windowed store's
    §4.5 all-time fold tier is NOT probed here (its levels are the same
    cell orders; open them with ``all_time=True``). ``product`` re-roots on
    a D19 multi-product subtree; ``manifest``/``store`` thread an
    already-read manifest and handle, per the issue-#5 posture.
    """
    from mortie import order2res

    if anonymous:
        store_kwargs.setdefault("anonymous", True)
    store_root, handle, manifest = _resolve_target(
        store_root, product, manifest, store, store_kwargs
    )
    table = pyramid_levels(manifest)
    windowed = manifest["spec"] == HIVE_SPEC_V2
    if window is not None:
        validate_window(window, where=store_root)
    if not windowed and window is not None:
        raise ValueError(
            f"window={window!r} on a {manifest['spec']} store: unwindowed stores "
            f"have no window leaves (schedule: none)"
        )
    needs_probe = probe and any(rec["artifact"] != "source" for rec in table.values())
    if needs_probe and windowed and window is None:
        raise ValueError(
            f"{store_root} is a windowed ({HIVE_SPEC_V2}) store; its pyramid artifacts "
            f"are per-window (D23 naming) — pass window=... to probe materialization, "
            f"or probe=False for the declared ladder alone"
        )

    # The source rung is True by definition on an unwindowed store — the
    # leaves ARE the store — but a windowed store's leaves are per window
    # (D23), so once a window is NAMED the same declared-vs-materialized
    # question applies to it as to every other rung, and it is probed.
    source_probe = probe and windowed and window is not None

    overview_presence: dict[int, OrderPresence] | None = None
    column_presence: dict[int, OrderPresence] | None = None
    source_presence: OrderPresence | None = None
    if needs_probe or source_probe:
        if needs_probe and any(rec["artifact"] == "overview" for rec in table.values()):
            info = read_pyramid(
                store_root,
                manifest=manifest,
                window=window,
                store=handle,
                concurrency=concurrency,
            )
            overview_presence = info.presence if info is not None else None
        leaf_cells = sorted(
            (rec["cell_order"] for rec in table.values() if rec["artifact"] == "column"),
            reverse=True,
        )
        if not needs_probe:
            leaf_cells = []
        if leaf_cells or source_probe:
            source_presence, column_presence = _leaf_presence(
                store_root,
                manifest,
                leaf_cells,
                window,
                handle,
                concurrency,
                source=source_probe,
            )

    decl = pyramid_declaration(manifest)
    multi_cell_nodes = {
        int(k) for k, cells in ((decl or {}).get("cell_orders") or {}).items() if len(cells) > 1
    }

    levels = []
    for rec in table.values():
        presence: OrderPresence | None = None
        if rec["artifact"] == "source":
            materialized: bool | None
            if not (windowed and window is not None):
                materialized = True  # the leaves ARE the store
            elif not probe:
                materialized = None  # a named window, declaration only
            else:
                presence = source_presence
                materialized = presence.stamped > 0 if presence is not None else None
        elif not needs_probe:
            materialized = None
        elif rec["artifact"] == "overview" and rec["order"] in multi_cell_nodes:
            # A /2 node declaring SEVERAL cell orders is backed by at most
            # one of them — its object's zagg_overview.cell_order is scalar
            # — and read_pyramid's probe is a bare node-existence count that
            # says nothing about which. Fanning that one count out to every
            # declared rung would tell the picker two orders are
            # materialized and then raise on the second (open_level names
            # the level explicitly, and _object_entry's wrong-cell_order
            # severity is a raise). Unknown is the honest answer the
            # existence probe can give.
            materialized = None
        elif rec["artifact"] == "overview":
            presence = (overview_presence or {}).get(rec["order"])
            materialized = presence.stamped > 0 if presence is not None else None
        else:
            presence = (column_presence or {}).get(rec["cell_order"])
            materialized = presence.stamped > 0 if presence is not None else None
        levels.append(
            LadderLevel(
                cell_order=rec["cell_order"],
                order=rec["order"],
                artifact=rec["artifact"],
                resolution_km=float(order2res(rec["cell_order"])),
                materialized=materialized,
                presence=presence,
            )
        )
    return Ladder(levels=tuple(levels))