views-frames 1.10.0__tar.gz → 1.10.2__tar.gz

{views_frames-1.10.0 → views_frames-1.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: views-frames
-Version: 1.10.0
+Version: 1.10.2
 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,7 @@ 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.10.0 — frozen API, published to PyPI** (frozen since v1.0.0, ADR-018; the
+> **Status:** **v1.10.2 — 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
@@ -53,7 +53,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). 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). 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.10.0 → views_frames-1.10.2}/README.md

@@ -4,7 +4,7 @@
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v1.10.0 — frozen API, published to PyPI** (frozen since v1.0.0, ADR-018; the
+> **Status:** **v1.10.2 — 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
@@ -21,7 +21,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). 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). 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.10.0 → views_frames-1.10.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "views-frames"
-version = "1.10.0"
+version = "1.10.2"
 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.10.0 → views_frames-1.10.2}/src/views_frames/feature_frame.py

@@ -1,10 +1,11 @@
 """`FeatureFrame` — model inputs (X): ``y_features (N, F, S)`` float32.
 
 A sibling frame (no shared base; ADR-011 Option C). Relocated from
-views-datafactory. The sample axis is **always explicit** (ADR-012): legacy 2D
-``(N, F)`` arrays are lifted to ``(N, F, 1)`` only through the explicit
-:meth:`from_2d` shim. Carries ``feature_names`` and a typed metadata header
-(ADR-013). ``from_grid`` is **not** here — it stays in views-datafactory.
+views-datafactory. The sample axis is **always explicit** (ADR-012), so
+unsampled features are stored as ``(N, F, 1)``; :meth:`from_2d` builds such a
+frame from a 2-D ``(N, F)`` array by adding that trailing axis. Carries
+``feature_names`` and a typed metadata header (ADR-013). ``from_grid`` is
+**not** here — it stays in views-datafactory.
 """
 
 from __future__ import annotations
@@ -38,7 +39,7 @@ class FeatureFrame:
             raise ValueError(
                 "FeatureFrame y_features must be 3D (N, F, S) with an explicit "
                 f"trailing sample axis (ADR-012), got ndim={values.ndim}. "
-                "Use FeatureFrame.from_2d to lift a legacy (N, F) array."
+                "Use FeatureFrame.from_2d to build a frame from a 2-D (N, F) array."
             )
         if values.shape[0] != index.n_rows:
             raise ValueError(
@@ -62,7 +63,12 @@ class FeatureFrame:
         feature_names: list[str],
         metadata: FrameMetadata | None = None,
     ) -> FeatureFrame:
-        """Lift a legacy 2D ``(N, F)`` array to ``(N, F, 1)`` (deprecated shim)."""
+        """Build a frame from a 2-D ``(N, F)`` array of unsampled features.
+
+        The sample axis is always explicit (ADR-012), so unsampled features are
+        stored as ``(N, F, 1)``. This adds that trailing axis for you. Raises
+        ``ValueError`` if the input is not 2-D.
+        """
         arr = coerce_values(y_features_2d)
         if arr.ndim != 2:
             raise ValueError(f"from_2d expects a 2D (N, F) array, got ndim={arr.ndim}")

{views_frames-1.10.0 → views_frames-1.10.2}/src/views_frames/io/arrow.py

@@ -71,7 +71,20 @@ def save(
 
 
 def load(path: Path | str) -> dict[str, Any]:
-    """Read a flat-columnar parquet frame state written by :func:`save`."""
+    """Read a flat-columnar parquet frame state written by :func:`save`.
+
+    The reconstruction is positional (``reshape(n, s)``), so the table's row
+    order **is** the contract: before trusting it, the wire-contract layout is
+    validated and any violation **raises** rather than reshaping plausible
+    floats into the wrong sample slots (ADR-013 §4.5b wire contract; #199).
+
+    Raises:
+        ValueError: the table is truncated/filtered (row count not a multiple
+            of the header's ``n_samples``), the ``sample`` column deviates from
+            the written ``tile(arange(S), N)`` order, or ``time``/``unit`` are
+            not constant within a row's sample block (rows swapped between
+            cells) — a reordered, truncated, or foreign-rewritten table.
+    """
     table = pq.read_table(str(path))
     raw = table.schema.metadata or {}
     header = json.loads(raw[b"views_frames"].decode())
@@ -80,9 +93,39 @@ def load(path: Path | str) -> dict[str, Any]:
 
     time_col = table.column("time").to_numpy()
     unit_col = table.column("unit").to_numpy()
-    n = time_col.shape[0] // s
-    time = time_col.reshape(n, s)[:, 0]
-    unit = unit_col.reshape(n, s)[:, 0]
+    total = int(time_col.shape[0])
+    if s <= 0 or total % s != 0:
+        raise ValueError(
+            f"corrupt frame parquet: {total} rows is not a positive multiple of "
+            f"the header's n_samples={s} — a truncated or filtered table cannot "
+            "be reshaped safely (wire contract, #199)"
+        )
+    n = total // s
+
+    sample_col = table.column("sample").to_numpy()
+    if not np.array_equal(sample_col, np.tile(np.arange(s, dtype=np.int32), n)):
+        raise ValueError(
+            "corrupt frame parquet: the 'sample' column deviates from the "
+            "written tile(arange(S), N) order — the table was reordered or "
+            "rewritten, so a positional reshape would silently place draws in "
+            "the wrong sample slots (wire contract, #199)"
+        )
+
+    time_blocks = time_col.reshape(n, s)
+    unit_blocks = unit_col.reshape(n, s)
+    if not (
+        bool((time_blocks == time_blocks[:, :1]).all())
+        and bool((unit_blocks == unit_blocks[:, :1]).all())
+    ):
+        raise ValueError(
+            "corrupt frame parquet: 'time'/'unit' are not constant within a "
+            "row's sample block — rows were swapped between cells, so a "
+            "positional reshape would silently misattribute draws "
+            "(wire contract, #199)"
+        )
+
+    time = time_blocks[:, 0]
+    unit = unit_blocks[:, 0]
 
     if ndim == 2:
         values = table.column("value").to_numpy().reshape(n, s).astype(np.float32)