views-frames 1.8.0__tar.gz → 1.8.1__tar.gz

{views_frames-1.8.0 → views_frames-1.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: views-frames
-Version: 1.8.0
+Version: 1.8.1
 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
@@ -36,14 +36,18 @@ 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.7.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1 surface is
+> **Status:** **v1.8.0 — frozen API, published to PyPI** (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; v1.7.0 adds a third
-> sibling package **`views_frames_reconcile`** — forecast reconciliation, ADR-023). This
+> sibling package **`views_frames_reconcile`** — forecast reconciliation, ADR-023; v1.8.0
+> adds the native point-country broadcast + the self-describing reconciliation mode,
+> the three showcase notebooks, and the frames-family hardening pass — Reconcile.md CIC,
+> ADR-025 immutability-by-convention, the adversarial red-test batch). 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

{views_frames-1.8.0 → views_frames-1.8.1}/README.md

@@ -4,14 +4,18 @@
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v1.7.0 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1 surface is
+> **Status:** **v1.8.0 — frozen API, published to PyPI** (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; v1.7.0 adds a third
-> sibling package **`views_frames_reconcile`** — forecast reconciliation, ADR-023). This
+> sibling package **`views_frames_reconcile`** — forecast reconciliation, ADR-023; v1.8.0
+> adds the native point-country broadcast + the self-describing reconciliation mode,
+> the three showcase notebooks, and the frames-family hardening pass — Reconcile.md CIC,
+> ADR-025 immutability-by-convention, the adversarial red-test batch). 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

{views_frames-1.8.0 → views_frames-1.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "views-frames"
-version = "1.8.0"
+version = "1.8.1"
 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.8.0 → views_frames-1.8.1}/src/views_frames/conformance/__init__.py

@@ -40,6 +40,20 @@ __all__ = [
 ]
 
 
+def _require_assertions() -> None:
+    """Fail loud if assertions are stripped (``python -O``/``-OO``).
+
+    The suite is built from ``assert`` statements; under optimized bytecode every
+    check would silently pass regardless of conformance — a verification tool that
+    reports green while dead (falsify audit 2026-07, F3). Refuse to run instead.
+    """
+    if not __debug__:  # pragma: no cover — pytest always runs with assertions on
+        raise RuntimeError(
+            "the views-frames conformance suite requires assertions; run without "
+            "python -O/-OO (PYTHONOPTIMIZE), otherwise every check silently passes"
+        )
+
+
 def assert_frame_envelope(frame: Any) -> None:
     """Assert ``frame`` satisfies the shared **frame envelope**.
 
@@ -56,6 +70,7 @@ def assert_frame_envelope(frame: Any) -> None:
     Raises:
         AssertionError: any part of the envelope is violated.
     """
+    _require_assertions()
     values = frame.values
     assert isinstance(values, np.ndarray), "values must be a numpy array"
     assert values.dtype == np.float32, f"values must be float32, got {values.dtype}"
@@ -77,6 +92,7 @@ def assert_frame_contract(frame: Any) -> None:
     Raises:
         AssertionError: the envelope or the spatiotemporal identifier rule is violated.
     """
+    _require_assertions()
     assert_frame_envelope(frame)
 
     ids = frame.identifiers
@@ -110,6 +126,7 @@ def assert_index_alignment_laws(index_a: Any, index_b: Any) -> None:
     Raises:
         AssertionError: a law is violated.
     """
+    _require_assertions()
     assert index_a.intersect(index_b) == index_b.intersect(index_a), (
         "intersect must be commutative"
     )
@@ -140,6 +157,7 @@ def assert_cross_level_alignment_law(
         AssertionError: the remap disagrees with the mapping, drops time, or
             produces the wrong level.
     """
+    _require_assertions()
     aligned = index.cross_level_align(mapping, target_level)
     assert aligned.level is target_level, "cross_level_align must carry target_level"
     assert np.array_equal(aligned.time, index.time), "cross_level_align must keep time"

{views_frames-1.8.0 → views_frames-1.8.1}/src/views_frames/index.py

@@ -132,6 +132,11 @@ class SpatioTemporalIndex:
         The pure-numpy analogue of ``pd.Index.get_indexer``: a same-level join.
         """
         self._require_same_level(other)
+        if self.n_rows == 0:
+            # An empty index contains nothing: every row of `other` is absent. The
+            # general path below would clip positions to -1 and crash with an
+            # obscure IndexError on the empty array (falsify audit 2026-07, F4).
+            return np.full(other.n_rows, -1, dtype=np.intp)
         self_rows = self._row_view(self._keys())
         other_rows = self._row_view(other._keys())
         order = np.argsort(self_rows, kind="stable")

{views_frames-1.8.0 → views_frames-1.8.1}/src/views_frames_reconcile/conformance.py

@@ -20,6 +20,19 @@ from views_frames import PredictionFrame, SpatialLevel
 from views_frames_reconcile.module import ReconciliationModule
 
 
+def _require_assertions() -> None:
+    """Fail loud if assertions are stripped (``python -O``/``-OO``).
+
+    Mirrors ``views_frames.conformance._require_assertions`` (falsify audit 2026-07,
+    F3): under optimized bytecode every ``assert`` silently passes — refuse to run.
+    """
+    if not __debug__:  # pragma: no cover — pytest always runs with assertions on
+        raise RuntimeError(
+            "the reconcile conformance suite requires assertions; run without "
+            "python -O/-OO (PYTHONOPTIMIZE), otherwise every check silently passes"
+        )
+
+
 def assert_reconcile_contract(
     cm_frame: PredictionFrame,
     pgm_frame: PredictionFrame,
@@ -35,6 +48,7 @@ def assert_reconcile_contract(
     Raises:
         AssertionError: a contract law is violated.
     """
+    _require_assertions()
     mk = np.asarray(map_keys)
     mv = np.asarray(map_vals)
     out = ReconciliationModule(mk, mv).reconcile(cm_frame, pgm_frame)

{views_frames-1.8.0 → views_frames-1.8.1}/src/views_frames_reconcile/proportional.py

@@ -9,6 +9,11 @@ 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).
+One deliberate deviation (falsify audit 2026-07): the original's ``+ 1e-8``
+denominator epsilon is replaced by an explicit all-zero-draw guard — bit-identical
+on all realistic data (the epsilon was a float32 no-op for draw sums ≳ 0.1) but
+exactly conserving for tiny nonzero sums, where the epsilon silently deflated the
+scale factor. Negative country totals now fail loud instead of silently clamping.
 It is intentionally the **same** method — a pragmatic per-draw approximation, not
 principled joint probabilistic reconciliation. The upgrade to the latter is designed
 in **ADR-024** (register **C-62**; the cross-repo lineage is views-postprocessing
@@ -27,8 +32,6 @@ 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,
@@ -49,7 +52,8 @@ def reconcile_proportional(
         are clamped to be non-negative.
 
     Raises:
-        ValueError: the grid and country sample counts disagree.
+        ValueError: the grid and country sample counts disagree, or any country
+            total is negative (cannot be conserved under the non-negativity clamp).
     """
     grid_arr = np.asarray(grid, dtype=np.float32)
     is_point = grid_arr.ndim == 1
@@ -65,13 +69,32 @@ def reconcile_proportional(
             f"Mismatch in sample count: grid has {grid_arr.shape[0]}, "
             f"country has {country_arr.shape[0]}"
         )
+    if bool((country_arr < 0).any()):
+        # A negative total cannot be conserved under the non-negativity clamp — the
+        # output would silently sum to 0, not the total (falsify audit 2026-07, F8).
+        raise ValueError(
+            "country totals must be non-negative; got a negative total "
+            f"(min={float(country_arr.min())}). A negative forecast is an upstream "
+            "bug; reconciliation cannot conserve it under the non-negativity clamp."
+        )
 
     # 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.
+    # Per-draw proportional scaling to the (authoritative) country total. Guard the
+    # all-zero draws explicitly (they carry no mass and stay zero — the documented
+    # edge) instead of an additive epsilon in the denominator: `+ 1e-8` was a no-op
+    # in float32 for sums ≳ 0.1 (machine eps exceeds it) but silently deflated the
+    # scale factor for tiny nonzero sums — at a draw sum of 1e-8 a country total of
+    # 100 reconciled to 50 with no error signal (falsify audit 2026-07, F1). The
+    # exact division below is bit-identical to the epsilon form on all realistic
+    # data (torch-oracle parity preserved) and conserves exactly for any nonzero sum.
     sum_nonzero = nonzero.sum(axis=1, keepdims=True)  # (S, 1)
-    scaling = country_arr.reshape(-1, 1) / (sum_nonzero + _EPS)  # (S, 1)
+    has_mass = sum_nonzero > 0
+    safe_sum = np.where(has_mass, sum_nonzero, np.float32(1.0))
+    scaling = np.where(
+        has_mass, country_arr.reshape(-1, 1) / safe_sum, np.float32(0.0)
+    )  # (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.8.0 → views_frames-1.8.1}/src/views_frames_summarize/conformance.py

@@ -22,12 +22,26 @@ from views_frames_summarize.tower import hdi_tower
 from views_frames_summarize.tower_point import tower_point
 
 
+def _require_assertions() -> None:
+    """Fail loud if assertions are stripped (``python -O``/``-OO``).
+
+    Mirrors ``views_frames.conformance._require_assertions`` (falsify audit 2026-07,
+    F3): under optimized bytecode every ``assert`` silently passes — refuse to run.
+    """
+    if not __debug__:  # pragma: no cover — pytest always runs with assertions on
+        raise RuntimeError(
+            "the summarize conformance suite requires assertions; run without "
+            "python -O/-OO (PYTHONOPTIMIZE), otherwise every check silently passes"
+        )
+
+
 def assert_summarizer_contract(frame: AnyFrame) -> None:
     """Assert the summarizers behave on ``frame``.
 
     Raises:
         AssertionError: a summarizer violates its output contract.
     """
+    _require_assertions()
     n = frame.n_rows
 
     point = collapse(frame, np.mean)