views-frames 1.3.0__tar.gz → 1.7.0__tar.gz

{views_frames-1.3.0 → views_frames-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: views-frames
-Version: 1.3.0
+Version: 1.7.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,15 +30,22 @@ 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.3.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1 surface is
+> **Status:** **v1.7.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). This README is the design
+> 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; v1.7.0 adds a third
+> sibling package **`views_frames_reconcile`** — forecast reconciliation, ADR-023). 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
 > `hdi_tower`/`tower_point`/`bimodality`/`summarize_tower`, + cross-level
-> aggregation; ADR-017, ADR-019). The blocking design decisions are resolved (§13a) and
+> aggregation; ADR-017, ADR-019) and the `src/views_frames_reconcile/` sibling package
+> (forecast reconciliation — make grid forecasts sum to country totals per draw; ADR-023).
+> The blocking design decisions are resolved (§13a) and
 > ratified as ADRs 011–018; two rounds of consumer review validated
 > the design. Consumer adoption (re-export shims, pandas migration) is the owner's
 > migration, not this repo's.
@@ -417,6 +424,14 @@ views-frames/
 │   ├── point.py                   # map_estimate (histogram MAP)
 │   ├── interval.py                # hdi, quantiles  → arrays aligned to the frame index
 │   └── aggregate.py               # conservation-correct cross-level aggregation
+├── src/views_frames_reconcile/    # forecast reconciliation OVER frames (ADR-023)
+│   ├── __init__.py                #   depends on views_frames + numpy only; never the reverse
+│   ├── proportional.py            # reconcile_proportional — per-draw top-down scaling
+│   ├── grouping.py                # reconcile_pgm_to_cm — group by (time, country)
+│   ├── frames.py                  # prediction_frame_from_arrays adapter
+│   ├── validation.py              # fail-loud input guards
+│   ├── module.py                  # ReconciliationModule (holds the injected mapping)
+│   └── conformance.py             # assert_reconcile_contract
 └── tests/
     ├── conformance/               # the published contract suite consumers re-run (see §9)
     └── unit/
@@ -439,6 +454,38 @@ Layout rules (these *are* the screaming-architecture requirements):
 - A new developer should infer every responsibility from the file tree without
   reading bodies.
 
+### 6a. The `views_frames_reconcile` sibling (ADR-023)
+
+Forecast **reconciliation** — making grid (`pgm`) predictions sum to their country
+(`cm`) totals — is a numpy-only frame→frame operation, structurally the same kind of
+thing as `views_frames_summarize` (ADR-017). It is its own sibling package, **not** in
+the leaf and **not** in views-postprocessing (its old, mis-homed host).
+
+**Charter.** **May:** forecast-reconciliation algorithms on frames (the per-draw
+top-down proportional method; future methods as sibling modules — the principled
+probabilistic upgrade, C-37); per-sample reconciliation; fail-loud validation; a
+conformance suite. **Must not:** IO; **fetch the `(time, unit) → country` mapping** (it
+is *injected* by the caller as numpy arrays, exactly like `cross_level_align` — ADR-014);
+actuals/scoring (views-evaluation); plotting; or any `views_*` import except
+`views_frames`. Import-DAG: `views_frames_reconcile → {views_frames}`.
+
+```python
+import numpy as np
+from views_frames_reconcile import ReconciliationModule
+
+# mapping is INJECTED by the caller (sourced from the producer; never fetched here):
+#   map_keys: (M, 2) int (time, priogrid_gid)   map_vals: (M,) int country_id
+reconciler = ReconciliationModule(map_keys, map_vals)
+pgm_reconciled = reconciler.reconcile(cm_frame, pgm_frame)  # new pgm PredictionFrame
+# each (time, country) group's cells now sum, per draw, to the country total
+# (all-zero grid draws stay zero); zeros preserved; non-negative.
+```
+
+> **Future DRY pass (deferred).** `grouping.py` labels grid rows by country with the
+> leaf's `cross_level_align_arrays` and overlaps `cross_level_align` (index.py). Folding
+> the two is a separate later story — the v1.7.0 relocation is a faithful **WET** move,
+> proven bit-identical to the original before any refactor.
+
 ---
 
 ## 7. On-disk / serialization contract (where "doesn't scale" is actually decided)

{views_frames-1.3.0 → views_frames-1.7.0}/README.md

@@ -4,15 +4,22 @@
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v1.3.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1 surface is
+> **Status:** **v1.7.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). This README is the design
+> 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; v1.7.0 adds a third
+> sibling package **`views_frames_reconcile`** — forecast reconciliation, ADR-023). 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
 > `hdi_tower`/`tower_point`/`bimodality`/`summarize_tower`, + cross-level
-> aggregation; ADR-017, ADR-019). The blocking design decisions are resolved (§13a) and
+> aggregation; ADR-017, ADR-019) and the `src/views_frames_reconcile/` sibling package
+> (forecast reconciliation — make grid forecasts sum to country totals per draw; ADR-023).
+> The blocking design decisions are resolved (§13a) and
 > ratified as ADRs 011–018; two rounds of consumer review validated
 > the design. Consumer adoption (re-export shims, pandas migration) is the owner's
 > migration, not this repo's.
@@ -391,6 +398,14 @@ views-frames/
 │   ├── point.py                   # map_estimate (histogram MAP)
 │   ├── interval.py                # hdi, quantiles  → arrays aligned to the frame index
 │   └── aggregate.py               # conservation-correct cross-level aggregation
+├── src/views_frames_reconcile/    # forecast reconciliation OVER frames (ADR-023)
+│   ├── __init__.py                #   depends on views_frames + numpy only; never the reverse
+│   ├── proportional.py            # reconcile_proportional — per-draw top-down scaling
+│   ├── grouping.py                # reconcile_pgm_to_cm — group by (time, country)
+│   ├── frames.py                  # prediction_frame_from_arrays adapter
+│   ├── validation.py              # fail-loud input guards
+│   ├── module.py                  # ReconciliationModule (holds the injected mapping)
+│   └── conformance.py             # assert_reconcile_contract
 └── tests/
     ├── conformance/               # the published contract suite consumers re-run (see §9)
     └── unit/
@@ -413,6 +428,38 @@ Layout rules (these *are* the screaming-architecture requirements):
 - A new developer should infer every responsibility from the file tree without
   reading bodies.
 
+### 6a. The `views_frames_reconcile` sibling (ADR-023)
+
+Forecast **reconciliation** — making grid (`pgm`) predictions sum to their country
+(`cm`) totals — is a numpy-only frame→frame operation, structurally the same kind of
+thing as `views_frames_summarize` (ADR-017). It is its own sibling package, **not** in
+the leaf and **not** in views-postprocessing (its old, mis-homed host).
+
+**Charter.** **May:** forecast-reconciliation algorithms on frames (the per-draw
+top-down proportional method; future methods as sibling modules — the principled
+probabilistic upgrade, C-37); per-sample reconciliation; fail-loud validation; a
+conformance suite. **Must not:** IO; **fetch the `(time, unit) → country` mapping** (it
+is *injected* by the caller as numpy arrays, exactly like `cross_level_align` — ADR-014);
+actuals/scoring (views-evaluation); plotting; or any `views_*` import except
+`views_frames`. Import-DAG: `views_frames_reconcile → {views_frames}`.
+
+```python
+import numpy as np
+from views_frames_reconcile import ReconciliationModule
+
+# mapping is INJECTED by the caller (sourced from the producer; never fetched here):
+#   map_keys: (M, 2) int (time, priogrid_gid)   map_vals: (M,) int country_id
+reconciler = ReconciliationModule(map_keys, map_vals)
+pgm_reconciled = reconciler.reconcile(cm_frame, pgm_frame)  # new pgm PredictionFrame
+# each (time, country) group's cells now sum, per draw, to the country total
+# (all-zero grid draws stay zero); zeros preserved; non-negative.
+```
+
+> **Future DRY pass (deferred).** `grouping.py` labels grid rows by country with the
+> leaf's `cross_level_align_arrays` and overlaps `cross_level_align` (index.py). Folding
+> the two is a separate later story — the v1.7.0 relocation is a faithful **WET** move,
+> proven bit-identical to the original before any refactor.
+
 ---
 
 ## 7. On-disk / serialization contract (where "doesn't scale" is actually decided)

{views_frames-1.3.0 → views_frames-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "views-frames"
-version = "1.3.0"
+version = "1.7.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" },
@@ -52,7 +52,7 @@ dev = [
 ]
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/views_frames", "src/views_frames_summarize"]
+packages = ["src/views_frames", "src/views_frames_summarize", "src/views_frames_reconcile"]
 
 [tool.hatch.build.targets.sdist]
 include = ["/src"]
@@ -87,6 +87,11 @@ select = ["E", "F", "I", "N", "UP", "B", "A", "C4", "SIM"]
 # The falsification stubs assert against the README via long, literal regexes
 # whose lines cannot wrap without changing their semantics.
 "tests/test_falsification_*.py" = ["E501"]
+# The reconciliation parity tests + their oracle-regeneration scripts are
+# faithfully relocated from views-postprocessing (Epic 11 / ADR-023); their dense
+# numpy/dict-comprehension assertions are kept verbatim rather than re-wrapped.
+"tests/test_reconciliation_*.py" = ["E501"]
+"scripts/gen_reconciliation_*.py" = ["E501"]
 
 [tool.mypy]
 python_version = "3.10"

{views_frames-1.3.0 → views_frames-1.7.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.3.0 → views_frames-1.7.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.7.0/src/views_frames_reconcile/__init__.py

@@ -0,0 +1,11 @@
+"""Forecast reconciliation (pgm forecasts reconciled to cm totals).
+
+Slice 1 ports the top-down proportional method from views-reporting as a pure
+numpy function. New methods (e.g. principled probabilistic reconciliation, C-37)
+should be added as sibling modules, not by modifying ``proportional``.
+"""
+
+from views_frames_reconcile.module import ReconciliationModule
+from views_frames_reconcile.proportional import reconcile_proportional
+
+__all__ = ["ReconciliationModule", "reconcile_proportional"]

views_frames-1.7.0/src/views_frames_reconcile/conformance.py

@@ -0,0 +1,74 @@
+"""Conformance checks for the reconcile package (ADR-023).
+
+A consumer can re-run these against its own frame factories to confirm the reconciler
+behaves: grid (``pgm``) predictions sum, per draw, to their country (``cm``) totals
+(except all-zero grid draws, which stay zero — the documented edge); zeros preserved;
+values stay non-negative; the output is a same-shape ``pgm`` ``PredictionFrame`` at PGM
+level; and the cm/pgm mapping is **injected, never fetched** (ADR-014/ADR-023).
+
+Mirrors ``views_frames_summarize/conformance.py:assert_summarizer_contract``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames import PredictionFrame, SpatialLevel
+from views_frames_reconcile.module import ReconciliationModule
+
+
+def assert_reconcile_contract(
+    cm_frame: PredictionFrame,
+    pgm_frame: PredictionFrame,
+    map_keys: NDArray[np.integer[Any]] | object,
+    map_vals: NDArray[np.integer[Any]] | object,
+) -> None:
+    """Assert the reconciler obeys its contract on ``(cm_frame, pgm_frame, mapping)``.
+
+    The mapping is **injected** (``map_keys``/``map_vals`` arrays) — never fetched
+    (enforced by the signature + the import-DAG; honoured here by the sum-to-country
+    law, which only holds if each cell is grouped under its injected country).
+
+    Raises:
+        AssertionError: a contract law is violated.
+    """
+    mk = np.asarray(map_keys)
+    mv = np.asarray(map_vals)
+    out = ReconciliationModule(mk, mv).reconcile(cm_frame, pgm_frame)
+
+    # 1. Output type / shape / level / index: a same-shape pgm PredictionFrame at PGM.
+    assert type(out) is type(pgm_frame), "reconcile must return the pgm frame type"
+    assert out.values.shape == pgm_frame.values.shape, "reconcile must preserve (N, S)"
+    assert out.index.level is SpatialLevel.PGM, "reconciled frame stays at PGM level"
+    assert np.array_equal(out.index.time, pgm_frame.index.time), "time index preserved"
+    assert np.array_equal(out.index.unit, pgm_frame.index.unit), "unit index preserved"
+
+    # 2. Non-negativity.
+    assert bool((out.values >= 0).all()), "reconciled forecasts must be non-negative"
+
+    # 3. Zero-preservation: an input zero cell stays zero.
+    assert bool((out.values[pgm_frame.values == 0] == 0).all()), "zeros preserved"
+
+    # 4. Sum-to-country per draw: each (time, country) group's cells sum, per draw, to
+    #    its country total — except all-zero input draws, which stay zero (the edge).
+    cm_units = pgm_frame.index.cross_level_align_arrays(mk, mv, SpatialLevel.CM).unit
+    pg_time = pgm_frame.index.time
+    cm_pos = {
+        (int(t), int(u)): j
+        for j, (t, u) in enumerate(
+            zip(cm_frame.index.time, cm_frame.index.unit, strict=True)
+        )
+    }
+    for t, c in np.unique(np.stack([pg_time, cm_units], axis=1), axis=0):
+        rows = (pg_time == t) & (cm_units == c)
+        in_sum = pgm_frame.values[rows].sum(axis=0)  # (S,)
+        out_sum = out.values[rows].sum(axis=0)  # (S,)
+        total = cm_frame.values[cm_pos[(int(t), int(c))]]  # (S,)
+        active = in_sum != 0
+        np.testing.assert_allclose(
+            out_sum[active], total[active], rtol=1e-4, atol=1e-3
+        )
+        assert bool((out_sum[~active] == 0).all()), "all-zero draws stay zero"

views_frames-1.7.0/src/views_frames_reconcile/frames.py

@@ -0,0 +1,69 @@
+"""Array → `PredictionFrame` adapters for reconciliation (epic #31, story #33).
+
+Reconciliation works on views-frames `PredictionFrame`s at two spatial levels:
+country (`cm`) and PRIO-GRID (`pgm`). Both are built the same way from
+`(time, unit, values)` arrays — only the `SpatialLevel` and the unit identifier
+(`country_id` vs `priogrid_gid`) differ. Predictions here carry a real posterior
+sample axis, so values are `(N, S)` with `S >= 1`.
+
+This is the reconciliation package's **own** I/O: it differs from the unfao
+delivery adapters (`unfao/frames.py`), which wrap pandas *scalar* columns as
+`(N, 1)` point frames — so per CRP they are not forced together. numpy +
+views-frames only; no torch, no pandas.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames import (
+    FrameMetadata,
+    PredictionFrame,
+    SpatialLevel,
+    SpatioTemporalIndex,
+)
+
+
+def prediction_frame_from_arrays(
+    time: NDArray[np.integer[Any]] | object,
+    unit: NDArray[np.integer[Any]] | object,
+    values: NDArray[np.floating[Any]] | object,
+    *,
+    level: SpatialLevel,
+    metadata: FrameMetadata | None = None,
+) -> PredictionFrame:
+    """Build a `PredictionFrame` from `(time, unit, values)` at ``level``.
+
+    Args:
+        time: 1-D integer array, length ``N`` (``month_id``).
+        unit: 1-D integer array, length ``N`` — ``country_id`` for
+            ``SpatialLevel.CM``, ``priogrid_gid`` for ``SpatialLevel.PGM``.
+        values: ``(N, S)`` float32-coercible array of posterior samples.
+        level: the frame's spatial level.
+
+    Returns:
+        A `PredictionFrame` of shape ``(N, S)`` at ``level``. The values buffer
+        is reused without copy when already float32 (views-frames C-07); the
+        input arrays are never mutated.
+
+    Raises:
+        ValueError: ``values`` is not 2-D, or ``time``/``unit`` are not 1-D of
+            length ``N``.
+    """
+    time_arr = np.asarray(time, dtype=np.int64)
+    unit_arr = np.asarray(unit, dtype=np.int64)
+    vals = np.asarray(values, dtype=np.float32)
+
+    if vals.ndim != 2:
+        raise ValueError(f"values must be 2-D (N, S); got ndim={vals.ndim}")
+    if time_arr.shape != (vals.shape[0],) or unit_arr.shape != (vals.shape[0],):
+        raise ValueError(
+            f"time {time_arr.shape} and unit {unit_arr.shape} must both be 1-D "
+            f"of length N={vals.shape[0]}"
+        )
+
+    index = SpatioTemporalIndex(time=time_arr, unit=unit_arr, level=level)
+    return PredictionFrame(vals, index, metadata)

views_frames-1.7.0/src/views_frames_reconcile/grouping.py

@@ -0,0 +1,92 @@
+"""Reconcile a pgm `PredictionFrame` to cm country totals (epic #31, story #34).
+
+The heart of the migration: for each `(time, country)`, scale that country's grid
+cells so their per-draw sum matches the country forecast, using the parity-proven
+leaf `reconcile_proportional` (PR #30). Grid rows are labelled by country with
+views-frames `cross_level_align` — the sanctioned cm↔pgm primitive, which fails
+loud if any grid row lacks a country (mirrors the original's "valid countries"
+guard). De-mutated: returns a **new** pgm frame (C-184); the input is untouched.
+
+numpy + views-frames only. The loop is over `(time, country)` groups (a small
+number), not over rows; each group call is fully vectorised over cells × samples.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames import PredictionFrame, SpatialLevel
+from views_frames_reconcile.proportional import reconcile_proportional
+
+
+def reconcile_pgm_to_cm(
+    pgm_frame: PredictionFrame,
+    cm_frame: PredictionFrame,
+    map_keys: NDArray[np.integer[Any]] | object,
+    map_vals: NDArray[np.integer[Any]] | object,
+) -> PredictionFrame:
+    """Return a new pgm `PredictionFrame` reconciled to ``cm_frame``'s totals.
+
+    Args:
+        pgm_frame: grid forecasts at PGM level, values ``(N_pg, S)``.
+        cm_frame: country forecasts at CM level, values ``(N_cm, S)``.
+        map_keys: ``(M, 2)`` int ``(time, priogrid_gid)`` covering every pgm row.
+        map_vals: ``(M,)`` int ``country_id`` for each key (injected; geography is
+            never embedded here — views-frames ADR-014).
+
+    Returns:
+        A new pgm `PredictionFrame` (same index/metadata as ``pgm_frame``) whose
+        cells sum, per draw, to the country forecast — except all-zero country
+        draws, which stay zero (the leaf's documented edge case).
+
+    Raises:
+        ValueError: a grid row has no country mapping (raised by
+            ``cross_level_align``), or a ``(time, country)`` group has no matching
+            country forecast in ``cm_frame``.
+    """
+    # 1. Label every grid row with its country (cm-level units); fails loud if a
+    #    row's (time, priogrid) is absent from the injected mapping.
+    cm_units = pgm_frame.index.cross_level_align_arrays(
+        np.asarray(map_keys), np.asarray(map_vals), SpatialLevel.CM
+    ).unit  # (N_pg,)
+    pg_time = pgm_frame.index.time
+
+    # 2. (time, country) -> row position in the country frame.
+    cm_time = cm_frame.index.time
+    cm_unit = cm_frame.index.unit
+    cm_vals = cm_frame.values
+    cm_pos = {(int(cm_time[j]), int(cm_unit[j])): j for j in range(cm_frame.n_rows)}
+
+    # 3. Group grid rows by (time, country) and reconcile each group with the leaf.
+    #    Group-by-sort: a single argsort lays the rows out contiguously per group
+    #    (O(N log N), one index array) — no per-group full-array scan — so it
+    #    scales to the full grid (register C-38). Group iteration order is
+    #    irrelevant: each group writes only its own rows.
+    pg_vals = pgm_frame.values
+    out = np.empty_like(pg_vals)
+    group_key = np.stack([pg_time, cm_units], axis=1)  # (N_pg, 2)
+    unique_groups, inverse, counts = np.unique(
+        group_key, axis=0, return_inverse=True, return_counts=True
+    )
+    inverse = np.asarray(inverse).reshape(-1)
+    order = np.argsort(inverse, kind="stable")  # rows grouped contiguously by group
+    # group gi -> order[bounds[gi]:bounds[gi + 1]]
+    bounds = np.concatenate(([0], np.cumsum(counts)))
+
+    for gi in range(unique_groups.shape[0]):
+        t, c = int(unique_groups[gi, 0]), int(unique_groups[gi, 1])
+        if (t, c) not in cm_pos:
+            raise ValueError(
+                f"grid group (time={t}, country={c}) has no country forecast "
+                "in cm_frame"
+            )
+        rows = order[bounds[gi]:bounds[gi + 1]]
+        country_total = cm_vals[cm_pos[(t, c)]]  # (S,)
+        # leaf convention: grid is (samples, cells); our frame slice is (cells, samples)
+        scaled = reconcile_proportional(pg_vals[rows].T, country_total)  # (S, n_cells)
+        out[rows] = scaled.T  # back to (n_cells, S)
+
+    return PredictionFrame(out, pgm_frame.index, pgm_frame.metadata)

views_frames-1.7.0/src/views_frames_reconcile/module.py

@@ -0,0 +1,68 @@
+"""Frames-native reconciliation orchestration (epic #31, story #36).
+
+`ReconciliationModule` holds the injected `(time, priogrid_gid) -> country_id`
+mapping (geography is injected, never embedded — views-frames ADR-014) and
+applies it: `reconcile(cm_frame, pgm_frame)` validates the inputs and scales the
+grid forecasts to the country totals, returning a **new** pgm frame (de-mutated,
+C-184).
+
+**SRP:** orchestration only — the scaling math is the leaf (`proportional`), the
+grouping is `grouping`, the guards are `validation`, the I/O is `frames`. No
+torch, no pandas, no viewser, no wandb: the original's `ProcessPoolExecutor` and
+WandB alerting are dropped (numpy is fast; there is no GPU). If scale ever needs
+parallelism, add it behind this same interface (OCP). Multi-target inputs are
+reconciled by calling `reconcile` once per target.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames import PredictionFrame
+from views_frames_reconcile.grouping import reconcile_pgm_to_cm
+from views_frames_reconcile.validation import validate_reconciliation_inputs
+
+
+class ReconciliationModule:
+    """Reconcile pgm forecasts to cm country totals (one target per call)."""
+
+    def __init__(
+        self,
+        map_keys: NDArray[np.integer[Any]] | object,
+        map_vals: NDArray[np.integer[Any]] | object,
+    ) -> None:
+        """Inject the `(time, priogrid_gid) -> country_id` mapping.
+
+        Args:
+            map_keys: ``(M, 2)`` int array of ``(time, priogrid_gid)`` pairs.
+            map_vals: ``(M,)`` int ``country_id`` for each key.
+
+        Raises:
+            ValueError: ``map_keys`` is not ``(M, 2)`` or ``map_vals`` is not
+                length ``M``.
+        """
+        keys = np.asarray(map_keys)
+        vals = np.asarray(map_vals)
+        if keys.ndim != 2 or keys.shape[1] != 2:
+            raise ValueError("map_keys must be an (M, 2) array of (time, priogrid_gid)")
+        if vals.shape != (keys.shape[0],):
+            raise ValueError("map_vals must be a length-M array aligned to map_keys")
+        self._map_keys = keys
+        self._map_vals = vals
+
+    def reconcile(
+        self, cm_frame: PredictionFrame, pgm_frame: PredictionFrame
+    ) -> PredictionFrame:
+        """Validate the inputs, then return a new pgm frame reconciled to cm totals.
+
+        Raises:
+            ValueError: the inputs fail validation (level / sample-count / time
+                coverage / missing country forecast).
+        """
+        validate_reconciliation_inputs(
+            cm_frame, pgm_frame, self._map_keys, self._map_vals
+        )
+        return reconcile_pgm_to_cm(pgm_frame, cm_frame, self._map_keys, self._map_vals)

views_frames-1.7.0/src/views_frames_reconcile/proportional.py

@@ -0,0 +1,74 @@
+"""Top-down proportional reconciliation (numpy port — phase 2, slice 1).
+
+Makes PRIO-GRID-month (pgm) forecasts sum to their country-month (cm) total by
+**top-down disaggregation using forecast proportions** (FPP3 terminology),
+applied **per posterior draw**: within a draw, each grid cell keeps its relative
+share and the cells are rescaled so they sum to that draw's country total. Zeros
+stay zero; country totals are authoritative; the result is non-negative.
+
+This is a *faithful, numpy-only* port of views-reporting's
+``ForecastReconciler.reconcile_forecast`` (torch), migrated here because the
+algorithm belongs in post-processing, not reporting (views-reporting issue #72).
+It is intentionally the **same** method — a pragmatic per-draw approximation, not
+principled joint probabilistic reconciliation. The upgrade to the latter is
+tracked as **C-37** and is deliberately deferred until this port's parity with
+the original is proven and the move is wired.
+
+No torch, no pandas — numpy only.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+_EPS = np.float32(1e-8)
+
+
+def reconcile_proportional(
+    grid: NDArray[np.floating[Any]] | object,
+    country: NDArray[np.floating[Any]] | float | object,
+) -> NDArray[np.float32]:
+    """Rescale grid forecasts so each draw sums to its country total.
+
+    Args:
+        grid: Grid-level forecasts, float32-coercible. Either
+            ``(num_samples, num_grid_cells)`` (probabilistic) or
+            ``(num_grid_cells,)`` (point).
+        country: Country-level total. Either ``(num_samples,)`` (probabilistic)
+            or a scalar (point). Must align with ``grid``'s sample axis.
+
+    Returns:
+        Adjusted grid forecasts, float32, same shape as ``grid``. ``sum`` over
+        grid cells equals ``country`` per sample; zero cells stay zero; values
+        are clamped to be non-negative.
+
+    Raises:
+        ValueError: the grid and country sample counts disagree.
+    """
+    grid_arr = np.asarray(grid, dtype=np.float32)
+    is_point = grid_arr.ndim == 1
+
+    if is_point:
+        grid_arr = grid_arr[np.newaxis, :]  # (1, N)
+        country_arr = np.asarray([country], dtype=np.float32)
+    else:
+        country_arr = np.asarray(country, dtype=np.float32).reshape(-1)
+
+    if grid_arr.shape[0] != country_arr.shape[0]:
+        raise ValueError(
+            f"Mismatch in sample count: grid has {grid_arr.shape[0]}, "
+            f"country has {country_arr.shape[0]}"
+        )
+
+    # Preserve zeros: only strictly-positive cells carry probability mass.
+    nonzero = np.where(grid_arr > 0, grid_arr, np.float32(0.0))
+
+    # Per-draw proportional scaling to the (authoritative) country total.
+    sum_nonzero = nonzero.sum(axis=1, keepdims=True)  # (S, 1)
+    scaling = country_arr.reshape(-1, 1) / (sum_nonzero + _EPS)  # (S, 1)
+    adjusted = np.clip(nonzero * scaling, 0.0, None).astype(np.float32)
+
+    return np.asarray(adjusted[0] if is_point else adjusted, dtype=np.float32)

views_frames-1.7.0/src/views_frames_reconcile/validation.py

@@ -0,0 +1,79 @@
+"""Fail-loud validation for reconciliation inputs (epic #31, story #35).
+
+Ports views-reporting `ReconciliationModule.__init__`'s guards to frames-native
+checks, run before any work. SRP: small, independently testable helpers — not
+buried in the orchestrator. The original's intents map as:
+
+  - dataset type checks            -> spatial-level guard (cm@CM, pgm@PGM)
+  - same time steps + exact overlap -> identical set of time values
+  - (per-draw scaling needs it)     -> equal `sample_count`
+  - valid countries                 -> every (time, country) the grid maps to has
+                                       a country forecast in the cm frame
+
+The original's "different time units" (e.g. month_id vs year_id) check is
+subsumed by the level guard; per-target intersection is handled by the
+orchestrator, since frames here are single-target.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames import PredictionFrame, SpatialLevel
+
+
+def validate_reconciliation_inputs(
+    cm_frame: PredictionFrame,
+    pgm_frame: PredictionFrame,
+    map_keys: NDArray[np.integer[Any]] | object,
+    map_vals: NDArray[np.integer[Any]] | object,
+) -> None:
+    """Raise ``ValueError`` if the reconciliation inputs are inconsistent.
+
+    Checks spatial levels, sample-count alignment, identical time coverage, and
+    that every country the grid maps to has a forecast in ``cm_frame``.
+    """
+    if cm_frame.index.level is not SpatialLevel.CM:
+        raise ValueError(
+            f"country frame must be at SpatialLevel.CM, got {cm_frame.index.level}"
+        )
+    if pgm_frame.index.level is not SpatialLevel.PGM:
+        raise ValueError(
+            f"grid frame must be at SpatialLevel.PGM, got {pgm_frame.index.level}"
+        )
+    if cm_frame.sample_count != pgm_frame.sample_count:
+        raise ValueError(
+            f"sample-count mismatch: cm has {cm_frame.sample_count}, "
+            f"pgm has {pgm_frame.sample_count}"
+        )
+
+    cm_times = {int(t) for t in np.unique(cm_frame.index.time)}
+    pg_times = {int(t) for t in np.unique(pgm_frame.index.time)}
+    if cm_times != pg_times:
+        raise ValueError(
+            "cm and pgm cover different time steps: "
+            f"cm-only={sorted(cm_times - pg_times)}, "
+            f"pgm-only={sorted(pg_times - cm_times)}"
+        )
+
+    # Valid countries: every (time, country) the grid maps to must have a forecast.
+    cm_units = pgm_frame.index.cross_level_align_arrays(
+        np.asarray(map_keys), np.asarray(map_vals), SpatialLevel.CM
+    ).unit
+    needed = {
+        (int(t), int(c))
+        for t, c in zip(pgm_frame.index.time, cm_units, strict=True)
+    }
+    have = {
+        (int(t), int(c))
+        for t, c in zip(cm_frame.index.time, cm_frame.index.unit, strict=True)
+    }
+    missing = needed - have
+    if missing:
+        raise ValueError(
+            f"{len(missing)} grid group(s) have no country forecast in cm_frame, "
+            f"e.g. {sorted(missing)[:5]}"
+        )

{views_frames-1.3.0 → views_frames-1.7.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.3.0 → views_frames-1.7.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.7.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.7.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)