views-frames 1.11.0__tar.gz → 2.0.0__tar.gz

{views_frames-1.11.0 → views_frames-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: views-frames
-Version: 1.11.0
+Version: 2.0.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
@@ -36,7 +36,11 @@ 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.11.0 — frozen API, published to PyPI** (frozen since v1.0.0, ADR-018; the
+> **Status:** **v2.0.0 — the version in this tree.** For what is actually published, see
+> [PyPI](https://pypi.org/project/views-frames/): between a release commit and its publish
+> job this number is deliberately ahead, so this banner tracks the source and never claims
+> a publication it cannot verify. API frozen at v1.0.0 (ADR-018) and broken once in 2.0.0
+> (ADR-028; 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
@@ -53,7 +57,7 @@ Description-Content-Type: text/markdown
 > `research/figures/` tower-figure toolkit; v1.10.0 adds the **dense-grid fill**
 > primitive — `reindex_fill(other, *, fill_value)` on all three frames +
 > `SpatioTemporalIndex.cartesian` + the published `assert_reindex_fill_law`, ADR-026,
-> unblocking pandas-free FAO ingestion; v1.10.1 makes `io.arrow.load` fail loudly on a parquet whose row order breaks the wire contract, #199; v1.10.2 changes no behaviour — it arms the documentation check in CI, turns eleven falsification tests from README-wording checks into behaviour checks, and records ADR-027 declining the construction shortcut; v1.11.0 corrects the published MAP-containment law, which was wrong on tied draws and so failed ~6% of rows on integer count posteriors — register C-88 — and makes the two IO codecs agree on a non-JSON metadata value, C-90; the rest of that release makes the governance documents match the code and adds the CI checks that keep them matching). This
+> unblocking pandas-free FAO ingestion; v1.10.1 makes `io.arrow.load` fail loudly on a parquet whose row order breaks the wire contract, #199; v1.10.2 changes no behaviour — it arms the documentation check in CI, turns eleven falsification tests from README-wording checks into behaviour checks, and records ADR-027 declining the construction shortcut; v1.11.0 corrects the published MAP-containment law, which was wrong on tied draws and so failed ~6% of rows on integer count posteriors — register C-88 — and makes the two IO codecs agree on a non-JSON metadata value, C-90; the rest of that release makes the governance documents match the code and adds the CI checks that keep them matching; **v2.0.0 is the first MAJOR** — a falsification audit found that a frame's `index` was never type-checked, so a frame (or any object with an `n_rows`) was accepted silently and the published `assert_summarizer_contract` then certified the result, and it now raises `TypeError`; riding it, `frame.values` becomes read-only (C-66) and `map_estimate` rejects non-finite draws (C-57), and `CONFORMANCE_FLOOR` moves to `2.0.0` — a correct consumer changes its version constraint and re-locks, nothing else, ADR-028). 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
@@ -265,13 +269,14 @@ makes it safe to depend on from everywhere (SDP).
 3. **Immutable value objects.** A frame is validated at construction and then
    treated as read-only. Operations (`collapse`, `select`, `with_metadata`)
    **return new frames**; they never mutate in place. (Directly forbids the
-   C-184 cross-repo-mutation anti-pattern.) **Enforced for the index, by
-   convention for the value buffer:** the identifier arrays (`time`/`unit`) are
-   write-protected (`setflags(write=False)`); the `values` buffer is left
-   **writeable on purpose** — so structural ops can share it zero-copy — and is
-   immutable *by convention*: mutating `.values` in place is unsupported and may
-   silently corrupt buffer-sharing frames (ADR-025 / register C-63; enforcing it
-   is a deferred MAJOR-rider). **Copy-vs-view:** structural and
+   C-184 cross-repo-mutation anti-pattern.) **Enforced for the index, and since 2.0.0
+   for the value buffer too:** the identifier arrays (`time`/`unit`) are
+   write-protected (`setflags(write=False)`); the `values` buffer was left
+   **writeable on purpose** — so structural ops can share it zero-copy — and was
+   immutable *by convention* **until 2.0.0**, which enforced it: `values` is now a
+   read-only **view**, so an in-place mutation raises instead of silently corrupting
+   buffer-sharing frames, while zero-copy, mmap and the caller's own array are all
+   preserved (ADR-028 / register C-66; the convention-only era is ADR-025 / C-63). **Copy-vs-view:** structural and
    metadata-only operations (`with_metadata`, contiguous `select`) return frames
    that **share** the underlying `values` buffer (numpy view / zero-copy), and a
    `mmap`-backed frame stays `mmap`-backed — a new frame must never copy a

{views_frames-1.11.0 → views_frames-2.0.0}/README.md

@@ -4,7 +4,11 @@
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v1.11.0 — frozen API, published to PyPI** (frozen since v1.0.0, ADR-018; the
+> **Status:** **v2.0.0 — the version in this tree.** For what is actually published, see
+> [PyPI](https://pypi.org/project/views-frames/): between a release commit and its publish
+> job this number is deliberately ahead, so this banner tracks the source and never claims
+> a publication it cannot verify. API frozen at v1.0.0 (ADR-018) and broken once in 2.0.0
+> (ADR-028; 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
@@ -21,7 +25,7 @@
 > `research/figures/` tower-figure toolkit; v1.10.0 adds the **dense-grid fill**
 > primitive — `reindex_fill(other, *, fill_value)` on all three frames +
 > `SpatioTemporalIndex.cartesian` + the published `assert_reindex_fill_law`, ADR-026,
-> unblocking pandas-free FAO ingestion; v1.10.1 makes `io.arrow.load` fail loudly on a parquet whose row order breaks the wire contract, #199; v1.10.2 changes no behaviour — it arms the documentation check in CI, turns eleven falsification tests from README-wording checks into behaviour checks, and records ADR-027 declining the construction shortcut; v1.11.0 corrects the published MAP-containment law, which was wrong on tied draws and so failed ~6% of rows on integer count posteriors — register C-88 — and makes the two IO codecs agree on a non-JSON metadata value, C-90; the rest of that release makes the governance documents match the code and adds the CI checks that keep them matching). This
+> unblocking pandas-free FAO ingestion; v1.10.1 makes `io.arrow.load` fail loudly on a parquet whose row order breaks the wire contract, #199; v1.10.2 changes no behaviour — it arms the documentation check in CI, turns eleven falsification tests from README-wording checks into behaviour checks, and records ADR-027 declining the construction shortcut; v1.11.0 corrects the published MAP-containment law, which was wrong on tied draws and so failed ~6% of rows on integer count posteriors — register C-88 — and makes the two IO codecs agree on a non-JSON metadata value, C-90; the rest of that release makes the governance documents match the code and adds the CI checks that keep them matching; **v2.0.0 is the first MAJOR** — a falsification audit found that a frame's `index` was never type-checked, so a frame (or any object with an `n_rows`) was accepted silently and the published `assert_summarizer_contract` then certified the result, and it now raises `TypeError`; riding it, `frame.values` becomes read-only (C-66) and `map_estimate` rejects non-finite draws (C-57), and `CONFORMANCE_FLOOR` moves to `2.0.0` — a correct consumer changes its version constraint and re-locks, nothing else, ADR-028). 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
@@ -233,13 +237,14 @@ makes it safe to depend on from everywhere (SDP).
 3. **Immutable value objects.** A frame is validated at construction and then
    treated as read-only. Operations (`collapse`, `select`, `with_metadata`)
    **return new frames**; they never mutate in place. (Directly forbids the
-   C-184 cross-repo-mutation anti-pattern.) **Enforced for the index, by
-   convention for the value buffer:** the identifier arrays (`time`/`unit`) are
-   write-protected (`setflags(write=False)`); the `values` buffer is left
-   **writeable on purpose** — so structural ops can share it zero-copy — and is
-   immutable *by convention*: mutating `.values` in place is unsupported and may
-   silently corrupt buffer-sharing frames (ADR-025 / register C-63; enforcing it
-   is a deferred MAJOR-rider). **Copy-vs-view:** structural and
+   C-184 cross-repo-mutation anti-pattern.) **Enforced for the index, and since 2.0.0
+   for the value buffer too:** the identifier arrays (`time`/`unit`) are
+   write-protected (`setflags(write=False)`); the `values` buffer was left
+   **writeable on purpose** — so structural ops can share it zero-copy — and was
+   immutable *by convention* **until 2.0.0**, which enforced it: `values` is now a
+   read-only **view**, so an in-place mutation raises instead of silently corrupting
+   buffer-sharing frames, while zero-copy, mmap and the caller's own array are all
+   preserved (ADR-028 / register C-66; the convention-only era is ADR-025 / C-63). **Copy-vs-view:** structural and
    metadata-only operations (`with_metadata`, contiguous `select`) return frames
    that **share** the underlying `values` buffer (numpy view / zero-copy), and a
    `mmap`-backed frame stays `mmap`-backed — a new frame must never copy a

{views_frames-1.11.0 → views_frames-2.0.0}/pyproject.toml

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

@@ -19,7 +19,8 @@ the envelope has one written authority rather than re-asserted copies that drift
     assert_frame_envelope(my_metric_frame())
 
 The floor is governed in ``GOVERNANCE.md``; ``CONFORMANCE_FLOOR`` records the version
-this suite belongs to.
+this suite belongs to. It moved to ``2.0.0`` with the 2.0.0 MAJOR (ADR-028) — the first
+move since the v1.0.0 freeze.
 """
 
 from __future__ import annotations
@@ -29,7 +30,11 @@ from typing import Any
 
 import numpy as np
 
-CONFORMANCE_FLOOR = "1.0.0"
+# Bumped to 2.0.0 on 2026-08-18 — the FIRST move since the freeze. `assert_summarizer_
+# contract` now rejects a frame whose index is not an index, which narrows what the
+# published suite accepts, and GOVERNANCE bumps the floor on any breaking change to any
+# published entry point. A consumer reading this learns which contract its CI asserts.
+CONFORMANCE_FLOOR = "2.0.0"
 
 __all__ = [
     "CONFORMANCE_FLOOR",

{views_frames-1.11.0 → views_frames-2.0.0}/src/views_frames/feature_frame.py

@@ -41,6 +41,10 @@ class FeatureFrame:
                 f"trailing sample axis (ADR-012), got ndim={values.ndim}. "
                 "Use FeatureFrame.from_2d to build a frame from a 2-D (N, F) array."
             )
+        if not isinstance(index, SpatioTemporalIndex):
+            raise TypeError(
+                f"index must be a SpatioTemporalIndex, got {type(index).__name__}"
+            )
         if values.shape[0] != index.n_rows:
             raise ValueError(
                 f"y_features has {values.shape[0]} rows but index has {index.n_rows}"
@@ -50,7 +54,13 @@ class FeatureFrame:
                 f"feature_names length ({len(feature_names)}) must match the "
                 f"feature axis ({values.shape[1]})"
             )
-        self._values = values
+        # A read-only *view*, not `values.setflags(write=False)` (register C-66).
+        # `coerce_values` returns the caller's own array when it is already float32
+        # (the C-07 zero-copy guarantee), so locking it in place would silently make
+        # the CALLER's array read-only — action at a distance well outside this
+        # contract. The view shares the buffer, so zero-copy and mmap are preserved.
+        self._values: NDArray[np.float32] = values.view()
+        self._values.setflags(write=False)
         self._index = index
         self._feature_names = list(feature_names)
         self._metadata = metadata if metadata is not None else FrameMetadata()

{views_frames-1.11.0 → views_frames-2.0.0}/src/views_frames/index.py

@@ -47,7 +47,11 @@ class SpatioTemporalIndex:
         is_array = isinstance(time, np.ndarray) and time.ndim >= 1
         n = int(time.shape[0]) if is_array else -1
         validate_identifiers({"time": time, "unit": unit}, n_rows=n)
-        # store as read-only views so the value object cannot be mutated in place
+        # Write-protect the identifier arrays so the value object cannot be mutated
+        # in place. Note `ascontiguousarray` returns the *same* array when the input
+        # is already contiguous, so this also write-protects the caller's array. That
+        # is long-standing index behaviour, deliberately left alone here; the frames
+        # take a read-only view instead, for the reason given in their constructors.
         self._time = np.ascontiguousarray(time)
         self._unit = np.ascontiguousarray(unit)
         self._time.setflags(write=False)
@@ -173,6 +177,16 @@ class SpatioTemporalIndex:
         )
 
     def _require_same_level(self, other: SpatioTemporalIndex) -> None:
+        # Type first. Every same-level binary op (`searchsorted`/`reindex`,
+        # `is_superset_of`, `intersect`) routes through here, so this one guard is
+        # what stops a non-index argument reaching `other._level` and leaking
+        # `AttributeError: '...' object has no attribute '_level'` — a private
+        # attribute of a class the caller never named. ADR-008 requires a
+        # ValueError/TypeError at every validation guard (falsify audit 2026-08-18).
+        if not isinstance(other, SpatioTemporalIndex):
+            raise TypeError(
+                f"expected a SpatioTemporalIndex, got {type(other).__name__}"
+            )
         if self._level != other._level:
             raise ValueError(
                 "same-level operation requires equal SpatialLevel; "

{views_frames-1.11.0 → views_frames-2.0.0}/src/views_frames/prediction_frame.py

@@ -37,11 +37,21 @@ class PredictionFrame:
             raise ValueError(
                 f"PredictionFrame y_pred must be 2D (N, S), got ndim={values.ndim}"
             )
+        if not isinstance(index, SpatioTemporalIndex):
+            raise TypeError(
+                f"index must be a SpatioTemporalIndex, got {type(index).__name__}"
+            )
         if values.shape[0] != index.n_rows:
             raise ValueError(
                 f"y_pred has {values.shape[0]} rows but index has {index.n_rows}"
             )
-        self._values = values
+        # A read-only *view*, not `values.setflags(write=False)` (register C-66).
+        # `coerce_values` returns the caller's own array when it is already float32
+        # (the C-07 zero-copy guarantee), so locking it in place would silently make
+        # the CALLER's array read-only — action at a distance well outside this
+        # contract. The view shares the buffer, so zero-copy and mmap are preserved.
+        self._values: NDArray[np.float32] = values.view()
+        self._values.setflags(write=False)
         self._index = index
         self._metadata = metadata if metadata is not None else FrameMetadata()
 

{views_frames-1.11.0 → views_frames-2.0.0}/src/views_frames/target_frame.py

@@ -36,11 +36,21 @@ class TargetFrame:
                 "TargetFrame y_true must have shape (N, 1) with an explicit "
                 f"trailing axis (ADR-012), got shape {values.shape}"
             )
+        if not isinstance(index, SpatioTemporalIndex):
+            raise TypeError(
+                f"index must be a SpatioTemporalIndex, got {type(index).__name__}"
+            )
         if values.shape[0] != index.n_rows:
             raise ValueError(
                 f"y_true has {values.shape[0]} rows but index has {index.n_rows}"
             )
-        self._values = values
+        # A read-only *view*, not `values.setflags(write=False)` (register C-66).
+        # `coerce_values` returns the caller's own array when it is already float32
+        # (the C-07 zero-copy guarantee), so locking it in place would silently make
+        # the CALLER's array read-only — action at a distance well outside this
+        # contract. The view shares the buffer, so zero-copy and mmap are preserved.
+        self._values: NDArray[np.float32] = values.view()
+        self._values.setflags(write=False)
         self._index = index
         self._metadata = metadata if metadata is not None else FrameMetadata()
 

{views_frames-1.11.0 → views_frames-2.0.0}/src/views_frames_summarize/conformance.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import numpy as np
 
+from views_frames import SpatioTemporalIndex
 from views_frames_summarize import config
 from views_frames_summarize._common import AnyFrame
 from views_frames_summarize.bimodality import bimodality
@@ -44,6 +45,23 @@ def assert_summarizer_contract(frame: AnyFrame) -> None:
         AssertionError: a summarizer violates its output contract.
     """
     _require_assertions()
+
+    # The frame must be structurally sound before any law about it means anything.
+    # Every summarizer below reads `frame.values` and `frame.n_rows` and none reads
+    # `frame.index`, so before 2.0.0 this suite returned cleanly for a frame whose
+    # index was not an index at all — a published checker issuing a false pass, which
+    # `docs/CICs/Conformance.md` names as the failure mode this module must never
+    # have (falsify audit 2026-08-18).
+    #
+    # Construction now rejects such a frame, so this is unreachable through the
+    # ordinary constructors. It is kept because consumers run this suite against
+    # *their own* frame factories under ADR-016, and `with_metadata` already builds
+    # frames through `Frame.__new__` rather than `__init__` — so a bypass path exists
+    # today and more may be added.
+    assert isinstance(frame.index, SpatioTemporalIndex), (
+        "frame.index must be a SpatioTemporalIndex, got "
+        f"{type(frame.index).__name__} — the frame misreports itself"
+    )
     n = frame.n_rows
 
     point = collapse(frame, np.mean)

{views_frames-1.11.0 → views_frames-2.0.0}/src/views_frames_summarize/point.py

@@ -44,6 +44,14 @@ def map_estimate(
     on such distributions; a robust mode estimator is tracked separately (#89).
     """
     values = frame.values
+    if not bool(np.isfinite(values).all()):
+        raise ValueError(
+            "map_estimate is undefined on non-finite draws (NaN or ±inf); strip or "
+            "impute upstream. Until 2.0.0 an inf draw reached the histogram and "
+            "crashed with an obscure IndexError from an integer overflow in the bin "
+            "index — loud, but it named neither the cause nor the caller. This is the "
+            "same guard exceedance and expected_shortfall carry (register C-57/C-50)"
+        )
     lead = values.shape[:-1]
     s = values.shape[-1]
     # Bin in the input dtype, exactly as the v0.2.0 per-row np.histogram did —