views-frames 1.2.0__tar.gz → 1.6.0__tar.gz

{views_frames-1.2.0 → views_frames-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: views-frames
-Version: 1.2.0
+Version: 1.6.0
 Summary: The VIEWS platform data-contract layer: immutable array+identifier frames (numpy only, root of the dependency DAG).
 Project-URL: Homepage, https://github.com/views-platform/views-frames
 Project-URL: Repository, https://github.com/views-platform/views-frames
@@ -30,9 +30,14 @@ Description-Content-Type: text/markdown
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v1.2.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1 surface is
-> purely additive — the coherent posterior summary, ADR-019; v1.2.0 rebuilds the tower
-> `outside-in` and makes it config-driven, register C-44). This README is the design
+> **Status:** **v1.6.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1 surface is
+> purely additive — the coherent posterior summary, ADR-019; v1.2.0 rebuilt the tower
+> `outside-in`, C-44; v1.3.0 makes the tower summary distribution-agnostic — no magnitude
+> zeroing by default, register C-45; v1.4.0 adds generic provenance to `FrameMetadata`
+> (`run_id`/`data_version`) and publishes the shared `assert_frame_envelope` checker,
+> ADR-020; v1.5.0 adds the threshold **exceedance** estimator `P(Y > c)`, ADR-021; v1.6.0
+> adds the worst-case **expected_shortfall** estimator, ADR-022). This
+> README is the design
 > bible; the contract it specifies is realised in `src/views_frames/` (index, frames,
 > io, conformance suite) plus the `src/views_frames_summarize/` sibling package
 > (sample-axis summarization — `collapse`/MAP/HDI/quantiles, the coherent-tower estimators
@@ -96,16 +101,20 @@ Both are numpy-only. For the subtler cm↔pgm surface — a time-varying
 `aggregate_distributions` (`HDI(sum) ≠ sum(HDI)`) — see
 [`examples/cross_level.py`](examples/cross_level.py).
 
-**Which estimator? (two coherent paths, v1.2.0).** Each frozen estimator has a
+**Which estimator? (two coherent paths, v1.3.0).** Each frozen estimator has a
 coherent-tower sibling (ADR-019): `map_estimate` ↔ `tower_point` (an unbinned
 median-of-the-`tip_mass`-floor point — the "shorth", free of `map_estimate`'s histogram
 tie-break bias **and** robust to minority duplicated draws, register C-44), and
 `hdi`/`quantiles` ↔ `hdi_tower(masses=…)` (HDIs built **outside-in**, nested **by
 construction** and reproducible — a mass's interval is identical regardless of which others
-you request), with `summarize_tower` returning all three in one pass. The tower's tunables
-live in `views_frames_summarize.config` (fail-loud, no silent defaults). Use the **frozen**
-estimators for parity with existing pipelines; use the **tower** path when you need coherent,
-reproducible bands plus a matching, duplicate-robust point.
+you request), with `summarize_tower` returning all three in one pass. The tower path is
+**distribution-agnostic** — it works for counts, continuous, normal, and `[0,1]`
+(rate/probability) targets, with **no magnitude zeroing by default** (zero-inflation is read
+off the floor's density, register C-45); a count consumer that wants "sub-1 ⇒ 0" opts in via
+`config['zero_cutoff']`. The tower's tunables live in `views_frames_summarize.config`
+(fail-loud, no silent defaults). Use the **frozen** estimators for parity with existing
+pipelines; use the **tower** path when you need coherent, reproducible bands plus a matching,
+duplicate-robust point.
 
 **Reading the `bimodality` flag.** It is a *deliberately conservative* heuristic, **not** a
 formal multimodality test — tuned for **zero false positives** at the cost of recall on

{views_frames-1.2.0 → views_frames-1.6.0}/README.md

@@ -4,9 +4,14 @@
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v1.2.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1 surface is
-> purely additive — the coherent posterior summary, ADR-019; v1.2.0 rebuilds the tower
-> `outside-in` and makes it config-driven, register C-44). This README is the design
+> **Status:** **v1.6.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1 surface is
+> purely additive — the coherent posterior summary, ADR-019; v1.2.0 rebuilt the tower
+> `outside-in`, C-44; v1.3.0 makes the tower summary distribution-agnostic — no magnitude
+> zeroing by default, register C-45; v1.4.0 adds generic provenance to `FrameMetadata`
+> (`run_id`/`data_version`) and publishes the shared `assert_frame_envelope` checker,
+> ADR-020; v1.5.0 adds the threshold **exceedance** estimator `P(Y > c)`, ADR-021; v1.6.0
+> adds the worst-case **expected_shortfall** estimator, ADR-022). This
+> README is the design
 > bible; the contract it specifies is realised in `src/views_frames/` (index, frames,
 > io, conformance suite) plus the `src/views_frames_summarize/` sibling package
 > (sample-axis summarization — `collapse`/MAP/HDI/quantiles, the coherent-tower estimators
@@ -70,16 +75,20 @@ Both are numpy-only. For the subtler cm↔pgm surface — a time-varying
 `aggregate_distributions` (`HDI(sum) ≠ sum(HDI)`) — see
 [`examples/cross_level.py`](examples/cross_level.py).
 
-**Which estimator? (two coherent paths, v1.2.0).** Each frozen estimator has a
+**Which estimator? (two coherent paths, v1.3.0).** Each frozen estimator has a
 coherent-tower sibling (ADR-019): `map_estimate` ↔ `tower_point` (an unbinned
 median-of-the-`tip_mass`-floor point — the "shorth", free of `map_estimate`'s histogram
 tie-break bias **and** robust to minority duplicated draws, register C-44), and
 `hdi`/`quantiles` ↔ `hdi_tower(masses=…)` (HDIs built **outside-in**, nested **by
 construction** and reproducible — a mass's interval is identical regardless of which others
-you request), with `summarize_tower` returning all three in one pass. The tower's tunables
-live in `views_frames_summarize.config` (fail-loud, no silent defaults). Use the **frozen**
-estimators for parity with existing pipelines; use the **tower** path when you need coherent,
-reproducible bands plus a matching, duplicate-robust point.
+you request), with `summarize_tower` returning all three in one pass. The tower path is
+**distribution-agnostic** — it works for counts, continuous, normal, and `[0,1]`
+(rate/probability) targets, with **no magnitude zeroing by default** (zero-inflation is read
+off the floor's density, register C-45); a count consumer that wants "sub-1 ⇒ 0" opts in via
+`config['zero_cutoff']`. The tower's tunables live in `views_frames_summarize.config`
+(fail-loud, no silent defaults). Use the **frozen** estimators for parity with existing
+pipelines; use the **tower** path when you need coherent, reproducible bands plus a matching,
+duplicate-robust point.
 
 **Reading the `bimodality` flag.** It is a *deliberately conservative* heuristic, **not** a
 formal multimodality test — tuned for **zero false positives** at the cost of recall on

{views_frames-1.2.0 → views_frames-1.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "views-frames"
-version = "1.2.0"
+version = "1.6.0"
 description = "The VIEWS platform data-contract layer: immutable array+identifier frames (numpy only, root of the dependency DAG)."
 authors = [
     { name = "Simon Polichinel von der Maase", email = "simmaa@prio.org" },

{views_frames-1.2.0 → views_frames-1.6.0}/src/views_frames/conformance/__init__.py

@@ -10,6 +10,14 @@ Usage in a consumer's test::
     from views_frames.conformance import assert_frame_contract
     assert_frame_contract(my_adapter_output())
 
+A consumer whose type is **not** spatiotemporal (a string-keyed evaluation output, e.g.
+views-evaluation's ``MetricFrame``) validates against the shared envelope instead, so
+the envelope has one written authority rather than re-asserted copies that drift
+(ADR-020, register C-46)::
+
+    from views_frames.conformance import assert_frame_envelope
+    assert_frame_envelope(my_metric_frame())
+
 The floor is governed in ``GOVERNANCE.md``; ``CONFORMANCE_FLOOR`` records the version
 this suite belongs to.
 """
@@ -27,20 +35,26 @@ __all__ = [
     "CONFORMANCE_FLOOR",
     "assert_cross_level_alignment_law",
     "assert_frame_contract",
+    "assert_frame_envelope",
     "assert_index_alignment_laws",
 ]
 
 
-def assert_frame_contract(frame: Any) -> None:
-    """Assert ``frame`` satisfies the views-frames data contract.
+def assert_frame_envelope(frame: Any) -> None:
+    """Assert ``frame`` satisfies the shared **frame envelope**.
+
+    The envelope is the subset of the contract that applies to *any* frame-like value
+    object, spatiotemporal or not: float32 values with no object dtype, an explicit
+    trailing axis, rows equal to ``n_rows``, and a save/load round-trip that preserves
+    the values and every identifier array. It deliberately says nothing about *which*
+    identifiers exist or their dtype — that is the spatiotemporal layer's concern.
 
-    Checks the structural invariants (float32 values, no object dtype, an explicit
-    trailing axis, complete integer identifiers of length ``n_rows``) and the
-    save/load round-trip. (Sample-axis reduction is the ``views_frames_summarize``
-    package's concern, not the contract's — ADR-017.)
+    This is the single written authority for the envelope so a sibling that re-asserts
+    it (views-evaluation's ``MetricFrame``, keyed by string axes — not ``(time, unit)``)
+    validates against this checker rather than drifting from it (ADR-020, C-46).
 
     Raises:
-        AssertionError: any part of the contract is violated.
+        AssertionError: any part of the envelope is violated.
     """
     values = frame.values
     assert isinstance(values, np.ndarray), "values must be a numpy array"
@@ -49,6 +63,22 @@ def assert_frame_contract(frame: Any) -> None:
     assert values.ndim >= 2, "values must have an explicit trailing sample axis"
     assert values.shape[0] == frame.n_rows, "values rows must equal n_rows"
 
+    _assert_roundtrip(frame)
+
+
+def assert_frame_contract(frame: Any) -> None:
+    """Assert ``frame`` satisfies the full views-frames **spatiotemporal** contract.
+
+    The shared envelope (:func:`assert_frame_envelope`) plus the spatiotemporal
+    requirement: complete integer ``time``/``unit`` identifiers of length ``n_rows``.
+    (Sample-axis reduction is the ``views_frames_summarize`` package's concern, not the
+    contract's — ADR-017.)
+
+    Raises:
+        AssertionError: the envelope or the spatiotemporal identifier rule is violated.
+    """
+    assert_frame_envelope(frame)
+
     ids = frame.identifiers
     for key in ("time", "unit"):
         assert key in ids, f"missing required identifier '{key}'"
@@ -56,14 +86,14 @@ def assert_frame_contract(frame: Any) -> None:
         assert np.issubdtype(arr.dtype, np.integer), f"'{key}' must be integer"
         assert arr.shape == (frame.n_rows,), f"'{key}' must be length n_rows"
 
-    _assert_roundtrip(frame)
-
 
 def _assert_roundtrip(frame: Any) -> None:
     with tempfile.TemporaryDirectory() as directory:
         frame.save(directory)
         loaded = type(frame).load(directory)
-        assert np.array_equal(loaded.values, frame.values), "save/load changed values"
+        assert np.array_equal(loaded.values, frame.values, equal_nan=True), (
+            "save/load changed values"
+        )
         for key, arr in frame.identifiers.items():
             assert np.array_equal(loaded.identifiers[key], arr), (
                 f"save/load changed identifier '{key}'"

{views_frames-1.2.0 → views_frames-1.6.0}/src/views_frames/metadata.py

@@ -3,6 +3,11 @@
 Not a free-form dict: a frozen dataclass with all-optional, validated fields, so
 adding a field is a MINOR change and consumers cannot diverge on key names (the
 store-side cause of reporting's C-48). It is the typed home for run/eval identity.
+
+Provenance fields are **generic only** (``run_id``, ``data_version``): meaningful for
+any frame. Evaluation-specific provenance (``scoring_code_version``, full-precision
+``evaluation_timestamp``) stays in views-evaluation's ``MetricFrame`` and must not leak
+into this generic header (ADR-020, register C-47).
 """
 
 from __future__ import annotations
@@ -20,6 +25,8 @@ class FrameMetadata:
     run_type: str | None = None
     timestamp: int | None = None
     seed: int | None = None
+    run_id: str | None = None
+    data_version: str | None = None
 
     def to_dict(self) -> dict[str, Any]:
         """Serialize to a plain dict, omitting unset (``None``) fields."""

{views_frames-1.2.0 → views_frames-1.6.0}/src/views_frames_summarize/__init__.py

@@ -17,6 +17,8 @@ from views_frames_summarize.aggregate import (
 )
 from views_frames_summarize.bimodality import bimodality
 from views_frames_summarize.collapse import collapse
+from views_frames_summarize.exceedance import exceedance, exceedance_reducer
+from views_frames_summarize.expected_shortfall import expected_shortfall
 from views_frames_summarize.interval import hdi, quantiles
 from views_frames_summarize.point import map_estimate
 from views_frames_summarize.summarize_tower import TowerSummary, summarize_tower
@@ -29,6 +31,9 @@ __all__ = [
     "aggregate_distributions_arrays",
     "bimodality",
     "collapse",
+    "exceedance",
+    "exceedance_reducer",
+    "expected_shortfall",
     "hdi",
     "hdi_tower",
     "map_estimate",

{views_frames-1.2.0 → views_frames-1.6.0}/src/views_frames_summarize/config.py

@@ -31,9 +31,12 @@ TOWER_CONFIG: Final[dict[str, Any]] = {
     # The tower-tip reads the median of the floor at this mass — the "shorth". 0.5 is
     # the maximally-robust choice: a duplicate would need ~half the draws to hijack it.
     "tip_mass": 0.5,
-    # Raw-count zero rule: a row whose every draw is <= this collapses to 0 (the quiet
-    # cell). A *count* rule, distinct from ``map_estimate``'s zero-mass-fraction rule.
-    "zero_cutoff": 1.0,
+    # Optional magnitude zero rule, OFF by default (``None``). When set to a float, a
+    # row whose every draw is <= it collapses to 0 — a *count* opt-in (sub-1 ⇒ 0).
+    # Left ``None`` for any non-count target: zero-inflation is otherwise handled by the
+    # density of the ``tip_mass`` floor, not by magnitude (register C-45). The leaf
+    # imposes no magnitude assumption by default; a consumer that wants it sets this.
+    "zero_cutoff": None,
     # Bimodality detector (coarse histogram + light smoothing; see bimodality.py).
     "bimodality_bins": 16,
     "bimodality_prominence": 0.40,

{views_frames-1.2.0 → views_frames-1.6.0}/src/views_frames_summarize/conformance.py

@@ -13,6 +13,8 @@ from views_frames_summarize import config
 from views_frames_summarize._common import AnyFrame
 from views_frames_summarize.bimodality import bimodality
 from views_frames_summarize.collapse import collapse
+from views_frames_summarize.exceedance import exceedance
+from views_frames_summarize.expected_shortfall import expected_shortfall
 from views_frames_summarize.interval import hdi, quantiles
 from views_frames_summarize.point import map_estimate
 from views_frames_summarize.summarize_tower import summarize_tower
@@ -44,6 +46,36 @@ def assert_summarizer_contract(frame: AnyFrame) -> None:
     assert qs.shape[0] == n, "quantiles must be aligned to the frame's rows"
     assert qs.shape[-1] == 3, "quantiles must produce one column per quantile"
 
+    # exceedance laws (ADR-021): a survival function — in [0, 1], non-increasing in the
+    # threshold, with P(> -inf) = 1 and P(> +inf) = 0.
+    thresholds = [-np.inf, 0.5, 1.5, np.inf]
+    exc = exceedance(frame, thresholds)
+    assert exc.shape[0] == n, "exceedance must be aligned to the frame's rows"
+    assert exc.shape[-1] == len(thresholds), "exceedance → one column per threshold"
+    assert ((exc >= 0.0) & (exc <= 1.0)).all(), (
+        "exceedance must be a probability in [0, 1]"
+    )
+    assert (np.diff(exc, axis=-1) <= 1e-6).all(), (
+        "exceedance must be non-increasing in the threshold"
+    )
+    assert (exc[..., 0] == 1.0).all(), "P(> -inf) must be 1"
+    assert (exc[..., -1] == 0.0).all(), "P(> +inf) must be 0"
+
+    # expected-shortfall laws (ADR-022): a tail mean — in [min, max], non-decreasing as
+    # the tail deepens (t → 0), and dominating its VaR (ES(t) ≥ the (1 − t) quantile).
+    tails = [1.0, 0.5, 0.1]  # widening tails (deepening worst-case)
+    es = expected_shortfall(frame, tails)
+    lo = frame.values.min(axis=-1)[..., np.newaxis]
+    hi = frame.values.max(axis=-1)[..., np.newaxis]
+    assert es.shape[0] == n, "expected_shortfall must be aligned to the frame's rows"
+    assert es.shape[-1] == len(tails), "expected_shortfall → one column per tail"
+    assert ((es >= lo - 1e-6) & (es <= hi + 1e-6)).all(), "ES must lie in [min, max]"
+    assert (np.diff(es, axis=-1) >= -1e-6).all(), (
+        "ES must be non-decreasing as the tail deepens"
+    )
+    var = quantiles(frame, [0.0, 0.5, 0.9])  # the (1 − t) quantiles for t = 1, 0.5, 0.1
+    assert (es >= var - 1e-6).all(), "ES(t) must dominate the (1 − t) quantile"
+
     _assert_tower_contract(frame, n)
 
 

views_frames-1.6.0/src/views_frames_summarize/exceedance.py

@@ -0,0 +1,96 @@
+"""Threshold exceedance probabilities over the sample axis (ADR-021).
+
+`exceedance(frame, thresholds)` returns the per-row empirical **survival fraction**
+`P(Y > c)` for each threshold — an index-aligned array `(N, …, K)`, the same shape/role
+family as `quantiles`. `exceedance_reducer(c)` is a `collapse`-compatible factory for
+the single-threshold `(N, …, 1)` **frame** path.
+
+Distribution-agnostic (a counting reducer — no histogram, no config, no unimodality
+assumption), so it is robust where the tower is weakest (register C-34); the flagship
+is `P(Y > 0)` = probability of any activity (onset). Thresholds are **required**
+per-call, in the frame's own units (an *input*, like `quantiles`' ``qs`` — never a
+tunable or a default). **Strict `>`** (register D-08). Fails loud on any non-finite
+draw — NaN or ±inf (register C-50) — and on empty thresholds; the joint-sample
+requirement for aggregate exceedance is the consumer's (C-49).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames_summarize._common import ROW_BLOCK, AnyFrame, block_apply
+from views_frames_summarize.collapse import Reducer
+
+
+def _exceed(
+    values: NDArray[np.float32], thresholds: NDArray[np.float64]
+) -> NDArray[np.float32]:
+    """Fraction of the trailing (sample) axis **strictly** greater than each threshold.
+
+    ``values`` is ``(…, S)`` and ``thresholds`` is ``(K,)``; returns ``(…, K)``.
+
+    Fails loud on any **non-finite** draw (NaN or ±inf): ``NaN > c`` is silently
+    ``False``, so a naive count would deflate ``P(Y > c)`` — worst on the ``P(Y > 0)``
+    onset flagship; and an ±inf draw (always an upstream bug) silently blesses ``P``
+    as a valid probability, masking the bug. A draw must be finite (C-50).
+    """
+    if not bool(np.isfinite(values).all()):
+        raise ValueError(
+            "exceedance is undefined on non-finite draws (NaN or ±inf); strip or "
+            "impute upstream (NaN > c is silently False and would deflate P(Y > c); "
+            "an inf draw masks an upstream bug behind a valid-looking P; register C-50)"
+        )
+    # (…, S) vs (K,) → (…, K, S) by broadcasting; strict ">"; mean over the sample axis.
+    above = values[..., np.newaxis, :] > thresholds[:, np.newaxis]
+    return np.asarray(above.mean(axis=-1), dtype=np.float32)
+
+
+def exceedance(
+    frame: AnyFrame,
+    thresholds: Sequence[float],
+    *,
+    block_rows: int = ROW_BLOCK,
+) -> NDArray[np.float32]:
+    """Per-row exceedance probability `P(Y > c)` over the sample axis → `(N, …, K)`.
+
+    For each of the ``K`` caller-supplied ``thresholds`` (required, in the frame's own
+    units), the empirical fraction of draws **strictly** greater than it. An
+    index-aligned numpy array (the caller holds the index), vectorized in row-blocks of
+    ``block_rows`` so peak memory is bounded by one block's working set (register C-25).
+
+    Raises:
+        ValueError: ``thresholds`` is empty (no default), or any draw is non-finite —
+            NaN or ±inf (C-50).
+    """
+    thr = np.asarray(thresholds, dtype=np.float64)
+    if thr.size == 0:
+        raise ValueError(
+            "exceedance requires at least one threshold; there is no default "
+            "(thresholds are an input in the frame's units, not a tunable — ADR-021)."
+        )
+
+    def _block(vals: NDArray[np.float32]) -> NDArray[np.float32]:
+        return _exceed(vals, thr)
+
+    out = block_apply(frame.values, block_rows, _block)
+    return np.asarray(out, dtype=np.float32)
+
+
+def exceedance_reducer(threshold: float) -> Reducer:
+    """A `collapse`-compatible reducer for single-threshold exceedance.
+
+    ``collapse(frame, exceedance_reducer(c))`` returns `P(Y > c)` as a `(N, …, 1)`
+    frame, sharing `exceedance`'s strict-`>` and fail-loud-non-finite policy (so a
+    consumer never re-implements ``np.mean(values > c)`` and drifts on the convention).
+    """
+    thr = np.asarray([threshold], dtype=np.float64)
+
+    def _reducer(values: NDArray[np.float32], axis: int = -1) -> NDArray[np.float32]:
+        # `collapse` calls reducer(values, axis=-1) and appends the trailing axis
+        # itself, so drop the singleton K axis (collapse re-adds the sample-axis slot).
+        return _exceed(values, thr)[..., 0]
+
+    return _reducer

views_frames-1.6.0/src/views_frames_summarize/expected_shortfall.py

@@ -0,0 +1,88 @@
+"""Worst-case scenario summary over the sample axis (ADR-022).
+
+`expected_shortfall(frame, tails)` returns the per-row **mean of the worst `⌈t·S⌉`
+draws** for each upper-tail fraction `t` — the tail mean / CVaR, a coherent worst-case
+risk measure and the companion to `exceedance`. An index-aligned array `(N, …, K)`, the
+same shape/role family as `quantiles`.
+
+`max` is deliberately **not** offered — it is the highest-variance, non-reproducible
+summary this replaces. Tails are **required** per-call, in `(0, 1]` (e.g. `0.01` = "the
+worst 1%") — the consumer's policy, never a default or config. Fails loud on any
+non-finite draw — NaN or ±inf (numpy sorts them *last*, so a naive top-`k` mean silently
+selects them — register C-56), on empty `tails`, and on any `t` outside `(0, 1]`.
+
+Written explicitly in its own module — it does **not** share a "tail reducer"
+abstraction with `quantiles`/`exceedance` (the duplication is shallow and the concerns
+change independently — WET before DRY). It reuses only the stable `_common` primitives.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames_summarize._common import ROW_BLOCK, AnyFrame, block_apply
+
+
+def _expected_shortfall(
+    values: NDArray[np.float32], tails: NDArray[np.float64]
+) -> NDArray[np.float32]:
+    """Mean of the worst ``⌈t·S⌉`` draws of the trailing (sample) axis, per tail.
+
+    ``values`` is ``(…, S)``, ``tails`` is ``(K,)`` in ``(0, 1]``; returns ``(…, K)``.
+
+    Fails loud on any **non-finite** draw (NaN or ±inf): numpy sorts NaN *last*, so a
+    top-`k` mean would silently select the NaNs — a NaN/garbage worst-case; and an ±inf
+    draw (always an upstream bug) sorts last and contaminates the tail mean to ±inf — a
+    degenerate "worst case". A draw must be a usable finite number (register C-56).
+    """
+    if not bool(np.isfinite(values).all()):
+        raise ValueError(
+            "expected_shortfall is undefined on non-finite draws (NaN or ±inf); strip "
+            "or impute upstream (numpy sorts NaN/+inf last, so the worst-k mean would "
+            "silently select them — a NaN/inf worst-case; register C-56)"
+        )
+    s = values.shape[-1]
+    srt = np.sort(values, axis=-1)  # ascending: the worst (largest) draws are last
+    out = np.empty((*values.shape[:-1], tails.shape[0]), dtype=np.float32)
+    for i in range(tails.shape[0]):
+        k = int(np.ceil(float(tails[i]) * s))  # number of worst draws to average (≥ 1)
+        out[..., i] = srt[..., s - k :].mean(axis=-1)
+    return out
+
+
+def expected_shortfall(
+    frame: AnyFrame,
+    tails: Sequence[float],
+    *,
+    block_rows: int = ROW_BLOCK,
+) -> NDArray[np.float32]:
+    """Per-row worst-case **expected shortfall** over the sample axis → `(N, …, K)`.
+
+    For each upper-tail fraction ``t`` in ``tails`` (required, in ``(0, 1]``), the mean
+    of the worst ``⌈t·S⌉`` draws — the average of the worst-case scenarios. An
+    index-aligned numpy array (the caller holds the index), block-applied in row-blocks.
+
+    Raises:
+        ValueError: ``tails`` is empty (no default), any ``t ∉ (0, 1]`` (a tail with no
+            samples), or any draw is non-finite — NaN or ±inf (register C-56).
+    """
+    thr = np.asarray(tails, dtype=np.float64)
+    if thr.size == 0:
+        raise ValueError(
+            "expected_shortfall requires at least one tail level; there is no default "
+            "(the tail fraction is an input in (0, 1], not a tunable — ADR-022)."
+        )
+    if bool(((thr <= 0.0) | (thr > 1.0)).any()):
+        raise ValueError(
+            f"expected_shortfall tails must be in (0, 1]; got {thr.tolist()} "
+            "(a tail <= 0 contains no samples; > 1 is not a fraction)."
+        )
+
+    def _block(vals: NDArray[np.float32]) -> NDArray[np.float32]:
+        return _expected_shortfall(vals, thr)
+
+    out = block_apply(frame.values, block_rows, _block)
+    return np.asarray(out, dtype=np.float32)

{views_frames-1.2.0 → views_frames-1.6.0}/src/views_frames_summarize/tower.py

@@ -13,9 +13,10 @@ nearest floor, never inserted — "the 50% HDI" is identical regardless of which
 masses a caller asks for (reproducibility).
 
 The construction is vectorized over the sample axis and runs in row-blocks (register
-C-22/C-25): one sort per block, never a whole-grid sorted copy. A raw-count zero
-short-circuit (`max(row) <= zero_cutoff` → the whole summary collapses to 0) kills the
-quiet cells cheaply.
+C-22/C-25): one sort per block, never a whole-grid sorted copy. Zero-inflation is read
+off the *density* of the `tip_mass` floor (a zero-majority row reads 0); an
+**optional, off-by-default** magnitude cutoff (`config['zero_cutoff']`, a count-domain
+opt-in) can additionally force `max(row) <= cutoff` rows to 0 (C-45).
 
 All tunables (the grid, zero cutoff, row-block size) come from `config` with **no silent
 defaults** (ADR-009). The private engine (`_dense_tower`, `_median_in`, `_pin`,
@@ -34,11 +35,10 @@ from numpy.typing import NDArray
 from views_frames_summarize import config
 from views_frames_summarize._common import AnyFrame, block_apply
 
-# The fixed canonical mass grid + the zero cutoff, sourced from the single config (no
-# silent defaults — ADR-009). Kept as module names so the engine and its siblings share
-# one source of truth.
+# The fixed canonical mass grid, sourced from the single config (no silent defaults —
+# ADR-009). The grid is reproducibility-fixed by design (ADR-019), so it is snapshotted
+# here; the *tunable* knobs (``zero_cutoff``, ``tip_mass``) are read live at call time.
 _CANONICAL_FLOORS: Final[NDArray[np.float64]] = config.canonical_floors()
-_ZERO_CUTOFF: Final[float] = float(config.get("zero_cutoff"))
 
 
 def _ks(sample_count: int) -> NDArray[np.intp]:
@@ -65,8 +65,18 @@ def _pin(masses: Sequence[float]) -> NDArray[np.intp]:
 
 
 def _zero_mask(block: NDArray[np.float32]) -> NDArray[np.bool_]:
-    """Rows whose maximum draw is at/below the zero cutoff — the quiet cells."""
-    return np.asarray(block.max(axis=-1) <= _ZERO_CUTOFF, dtype=np.bool_)
+    """Rows the optional magnitude cutoff zeroes — ``max(draws) <= zero_cutoff``.
+
+    **Off by default** (``zero_cutoff is None`` ⇒ no row is masked). A consumer that
+    wants magnitude zeroing (a count target where a sub-1 posterior should read 0) sets
+    ``zero_cutoff`` to a float in ``config`` — read **live** here, so the knob takes
+    effect at runtime. By default the leaf imposes **no** magnitude assumption; zero-
+    inflation is handled by the density of the ``tip_mass`` floor instead (C-45).
+    """
+    cutoff = config.get("zero_cutoff")
+    if cutoff is None:
+        return np.zeros(block.shape[0], dtype=np.bool_)
+    return np.asarray(block.max(axis=-1) <= cutoff, dtype=np.bool_)
 
 
 def _in_range_span(
@@ -203,8 +213,9 @@ def hdi_tower(
     Each requested mass is pinned to the nearest fixed canonical floor; the interval is
     read out of the full canonical tower (built once per block, outside-in). Nested by
     construction, robust to minority duplicates, and reproducible (a mass's interval is
-    independent of the other requested masses). Quiet rows (``max <= zero_cutoff``)
-    collapse to ``(0, 0)``. Aligned to ``frame.index``. Tunables come from ``config``.
+    independent of the other requested masses). If the optional ``zero_cutoff`` is set,
+    ``max <= cutoff`` rows collapse to ``(0, 0)`` (off by default — C-45). Aligned to
+    ``frame.index``. Tunables come from ``config``.
     """
     values = frame.values
     lead = values.shape[:-1]

{views_frames-1.2.0 → views_frames-1.6.0}/src/views_frames_summarize/tower_point.py

@@ -2,8 +2,8 @@
 
 `tower_point` is the "most likely single value" we report to a consumer: the median of
 the draws inside the **`tip_mass` floor** of the nested tower (config-driven, default
-0.5 — the "shorth"), with the same raw-count zero short-circuit as the tower
-(`max(row) <= zero_cutoff` → 0).
+0.5 — the "shorth"). Zero-inflation is handled by that floor's density (a zero-majority
+row reads 0); the optional, off-by-default magnitude cutoff applies too if set (C-45).
 
 It is a *new* estimator, deliberately distinct from the frozen `map_estimate` (ADR-018):
 `map_estimate` is a binned histogram mode with a zero-*mass*-fraction rule and a
@@ -34,9 +34,10 @@ from views_frames_summarize.tower import (
 def tower_point(frame: AnyFrame) -> AnyFrame:
     """Per-row tower-tip point estimate over the sample axis → a `(N, …, 1)` frame.
 
-    The median of the ``tip_mass`` floor's samples; ``0.0`` for quiet rows (every draw
-    ``<= zero_cutoff``). Returns a frame of the same type as ``frame``. Tunables (the
-    ``tip_mass``, the grid, the zero cutoff, the row-block) come from ``config``.
+    The median of the ``tip_mass`` floor's samples (``0`` when the zero atom dominates,
+    by density); if the optional ``zero_cutoff`` is set, ``max <= cutoff`` rows are
+    forced to ``0`` (off by default — C-45). Returns the same frame type as ``frame``.
+    Tunables (``tip_mass``, grid, ``zero_cutoff``, row-block) come from ``config``.
     """
     values = frame.values
     lead = values.shape[:-1]