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

{views_frames-1.10.2 → views_frames-2.0.0}/.gitignore

@@ -47,3 +47,6 @@ research/**/audit_plots/
 
 # generated figures (research/figures/ generators; deliverable copies travel with the deliverable)
 reports/plots/
+
+# knowledge-graph output (/graphify) — regenerated on demand, ~3.6 MB
+graphify-out/

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: views-frames
-Version: 1.10.2
+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.10.2 — 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). 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
@@ -433,24 +438,36 @@ views-frames/
 ├── LICENSE
 ├── src/views_frames/              # the pure data contract (numpy only, depends on nothing)
 │   ├── __init__.py                # EXPLICIT re-exports only (no `import *`)
-│   ├── index.py                   # SpatioTemporalIndex value object + alignment
+│   ├── _typing.py                 # IntArray / Float32Array aliases (private)
+│   ├── metadata.py                # FrameMetadata — the typed provenance header
 │   ├── spatial_level.py           # SpatialLevel enum (cm/pgm) — relocated here
-│   ├── protocols.py               # Frame / SpatioTemporalIndexed / Sampled / Persistable
 │   ├── _validation.py             # shared construction-time invariants (private helper)
+│   ├── index.py                   # SpatioTemporalIndex value object + alignment
+│   ├── protocols.py               # Frame / SpatioTemporalIndexed / Sampled / Persistable
 │   ├── feature_frame.py           # FeatureFrame              ── one concept per file
 │   ├── prediction_frame.py        # PredictionFrame
 │   ├── target_frame.py            # TargetFrame
 │   ├── conformance/               # the published contract suite consumers re-run (§9)
-│   └── io/                        # serialization adapters — SEPARATE from frames (SRP)
+│   │   └── __init__.py
+│   └── io/                        # serialization adapters — raw arrays in, files out
 │       ├── __init__.py
 │       ├── npz.py                 # native save()/load() (.npy + .npz)
 │       └── arrow.py               # flat columnar (.parquet) — the scalable disk format
 ├── src/views_frames_summarize/    # sample-axis summarization OVER frames (ADR-017)
 │   ├── __init__.py                #   depends on views_frames + numpy only; never the reverse
+│   ├── _common.py                 # block_apply / rebuild — the package's shared spine
+│   ├── config.py                  # tower-family tunables; fail-loud, no defaults
 │   ├── collapse.py                # collapse(frame, reducer) — generic point fold
 │   ├── point.py                   # map_estimate (histogram MAP)
 │   ├── interval.py                # hdi, quantiles  → arrays aligned to the frame index
-│   └── aggregate.py               # conservation-correct cross-level aggregation
+│   ├── tower.py                   # the constrained-nested HDI tower (ADR-019)
+│   ├── tower_point.py             # the tower-tip point estimate
+│   ├── bimodality.py              # per-row multimodality flag
+│   ├── summarize_tower.py         # single-pass coherent summary → TowerSummary
+│   ├── exceedance.py              # threshold exceedance probabilities (ADR-021)
+│   ├── expected_shortfall.py      # worst-case tail mean (ADR-022)
+│   ├── aggregate.py               # conservation-correct cross-level aggregation
+│   └── conformance.py             # assert_summarizer_contract
 ├── 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
@@ -458,19 +475,24 @@ views-frames/
 │   ├── frames.py                  # prediction_frame_from_arrays adapter
 │   ├── validation.py              # fail-loud input guards
 │   ├── module.py                  # ReconciliationModule (holds the injected mapping)
+│   ├── result.py                  # ReconciliationResult — the frame plus HOW it was made
 │   └── conformance.py             # assert_reconcile_contract
-└── tests/
-    ├── conformance/               # the published contract suite consumers re-run (see §9)
-    └── unit/
+├── scripts/                       # standalone dev tools, none wired into CI
+├── examples/                      # runnable quickstarts (run by CI)
+└── tests/                         # flat: test_*.py + fixtures/
 ```
 
 Layout rules (these *are* the screaming-architecture requirements):
 
 - **One main class/concept per file.** Multiple classes in a file is the
   exception, allowed only for genuinely inseparable units.
-- **Serialization is not the frame's job.** I/O adapters live under `io/`, import
-  the frame, and change for *their own* reasons (a new store format) — not when
-  the frame's schema changes (SRP + CCP). `PredictionFrameConverter`
+- **Serialization logic does not live in a frame file.** The codecs under `io/`
+  take **raw arrays** — `npz.save` is handed `values`, `time`, `unit`, `level`
+  and `metadata` separately — and change for *their own* reasons (a new store
+  format), not when a frame's schema changes (SRP + CCP). They never import a
+  frame; a frame's `save`/`load` are thin delegations *down* into them, because
+  `Persistable` places those methods on the frame (ADR-002, amended 2026-08-17,
+  register C-82). `PredictionFrameConverter`
   (PF↔list-in-cell DataFrame, a pipeline-core boundary format) **stays in
   pipeline-core**; it is an adapter, not a frame concern.
 - **No dumping grounds.** A file accumulating loose helpers/types/constants/
@@ -559,7 +581,8 @@ Because everyone depends on this, breakage is expensive — version it as a
 
 ## 9. Testing strategy (closes the cross-repo contract-test gap, C-30)
 
-- **Conformance suite (`tests/conformance/`):** a *published*, importable set of
+- **Conformance suite (`views_frames.conformance`, shipped in the wheel at
+  `src/views_frames/conformance/`):** a *published*, importable set of
   contract tests asserting the invariants of each Protocol (round-trip
   save/load, identifier completeness, collapse semantics, alignment laws). Every
   consumer repo runs it in CI against its own adapters. This is the missing

{views_frames-1.10.2 → 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.10.2 — 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). 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
@@ -401,24 +406,36 @@ views-frames/
 ├── LICENSE
 ├── src/views_frames/              # the pure data contract (numpy only, depends on nothing)
 │   ├── __init__.py                # EXPLICIT re-exports only (no `import *`)
-│   ├── index.py                   # SpatioTemporalIndex value object + alignment
+│   ├── _typing.py                 # IntArray / Float32Array aliases (private)
+│   ├── metadata.py                # FrameMetadata — the typed provenance header
 │   ├── spatial_level.py           # SpatialLevel enum (cm/pgm) — relocated here
-│   ├── protocols.py               # Frame / SpatioTemporalIndexed / Sampled / Persistable
 │   ├── _validation.py             # shared construction-time invariants (private helper)
+│   ├── index.py                   # SpatioTemporalIndex value object + alignment
+│   ├── protocols.py               # Frame / SpatioTemporalIndexed / Sampled / Persistable
 │   ├── feature_frame.py           # FeatureFrame              ── one concept per file
 │   ├── prediction_frame.py        # PredictionFrame
 │   ├── target_frame.py            # TargetFrame
 │   ├── conformance/               # the published contract suite consumers re-run (§9)
-│   └── io/                        # serialization adapters — SEPARATE from frames (SRP)
+│   │   └── __init__.py
+│   └── io/                        # serialization adapters — raw arrays in, files out
 │       ├── __init__.py
 │       ├── npz.py                 # native save()/load() (.npy + .npz)
 │       └── arrow.py               # flat columnar (.parquet) — the scalable disk format
 ├── src/views_frames_summarize/    # sample-axis summarization OVER frames (ADR-017)
 │   ├── __init__.py                #   depends on views_frames + numpy only; never the reverse
+│   ├── _common.py                 # block_apply / rebuild — the package's shared spine
+│   ├── config.py                  # tower-family tunables; fail-loud, no defaults
 │   ├── collapse.py                # collapse(frame, reducer) — generic point fold
 │   ├── point.py                   # map_estimate (histogram MAP)
 │   ├── interval.py                # hdi, quantiles  → arrays aligned to the frame index
-│   └── aggregate.py               # conservation-correct cross-level aggregation
+│   ├── tower.py                   # the constrained-nested HDI tower (ADR-019)
+│   ├── tower_point.py             # the tower-tip point estimate
+│   ├── bimodality.py              # per-row multimodality flag
+│   ├── summarize_tower.py         # single-pass coherent summary → TowerSummary
+│   ├── exceedance.py              # threshold exceedance probabilities (ADR-021)
+│   ├── expected_shortfall.py      # worst-case tail mean (ADR-022)
+│   ├── aggregate.py               # conservation-correct cross-level aggregation
+│   └── conformance.py             # assert_summarizer_contract
 ├── 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
@@ -426,19 +443,24 @@ views-frames/
 │   ├── frames.py                  # prediction_frame_from_arrays adapter
 │   ├── validation.py              # fail-loud input guards
 │   ├── module.py                  # ReconciliationModule (holds the injected mapping)
+│   ├── result.py                  # ReconciliationResult — the frame plus HOW it was made
 │   └── conformance.py             # assert_reconcile_contract
-└── tests/
-    ├── conformance/               # the published contract suite consumers re-run (see §9)
-    └── unit/
+├── scripts/                       # standalone dev tools, none wired into CI
+├── examples/                      # runnable quickstarts (run by CI)
+└── tests/                         # flat: test_*.py + fixtures/
 ```
 
 Layout rules (these *are* the screaming-architecture requirements):
 
 - **One main class/concept per file.** Multiple classes in a file is the
   exception, allowed only for genuinely inseparable units.
-- **Serialization is not the frame's job.** I/O adapters live under `io/`, import
-  the frame, and change for *their own* reasons (a new store format) — not when
-  the frame's schema changes (SRP + CCP). `PredictionFrameConverter`
+- **Serialization logic does not live in a frame file.** The codecs under `io/`
+  take **raw arrays** — `npz.save` is handed `values`, `time`, `unit`, `level`
+  and `metadata` separately — and change for *their own* reasons (a new store
+  format), not when a frame's schema changes (SRP + CCP). They never import a
+  frame; a frame's `save`/`load` are thin delegations *down* into them, because
+  `Persistable` places those methods on the frame (ADR-002, amended 2026-08-17,
+  register C-82). `PredictionFrameConverter`
   (PF↔list-in-cell DataFrame, a pipeline-core boundary format) **stays in
   pipeline-core**; it is an adapter, not a frame concern.
 - **No dumping grounds.** A file accumulating loose helpers/types/constants/
@@ -527,7 +549,8 @@ Because everyone depends on this, breakage is expensive — version it as a
 
 ## 9. Testing strategy (closes the cross-repo contract-test gap, C-30)
 
-- **Conformance suite (`tests/conformance/`):** a *published*, importable set of
+- **Conformance suite (`views_frames.conformance`, shipped in the wheel at
+  `src/views_frames/conformance/`):** a *published*, importable set of
   contract tests asserting the invariants of each Protocol (round-trip
   save/load, identifier completeness, collapse semantics, alignment laws). Every
   consumer repo runs it in CI against its own adapters. This is the missing

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "views-frames"
-version = "1.10.2"
+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" },
@@ -65,6 +65,53 @@ dev = [
     # pyarrow is the consumer-facing [arrow] extra; installed in dev so CI
     # exercises io/arrow. It must never be imported outside src/views_frames/io/.
     "pyarrow>=14,<20",
+    # Enforces [tool.importlinter] below. All three packages are cycle-free today;
+    # this keeps them that way rather than discovering otherwise in six months.
+    "import-linter>=2.0",
+    # tomllib is stdlib from 3.11; the 3.10 floor needs the backport, or
+    # tests/test_packaging.py collects nothing on the leg the floor job exists for
+    # (register C-80).
+    "tomli>=2; python_version<'3.11'",
+]
+
+# Both contracts record the dependency direction the code already has — they are not a
+# new architecture. `|` between siblings means *independent*: they may not import each
+# other, which is what actually prevents a cycle. (`:` would permit it.)
+#
+# Contract 1 duplicates tests/test_import_enforcement.py, which is stricter (it also bans
+# foreign views_* packages, pandas et al., and pyarrow outside io/). The duplication is
+# deliberate: the same contract is landing across the platform's cycle-free repos, so it
+# is written the same way here. Do not delete the test believing this replaces it.
+[tool.importlinter]
+root_packages = ["views_frames", "views_frames_summarize", "views_frames_reconcile"]
+
+[[tool.importlinter.contracts]]
+name = "The core does not depend on its consumers"
+type = "layers"
+layers = [
+    "views_frames_summarize | views_frames_reconcile",
+    "views_frames",
+]
+
+# `conformance` is in the top layer because that is its role — it validates frames from
+# outside. It imports nothing internal today (it duck-types against `Any`), so it would
+# satisfy any layer; putting it at the bottom would break this contract the first time
+# someone added a frame import for a type hint.
+#
+# NOTE: `io` sits *below* the frames because that is what the code does — `io/npz` and
+# `io/arrow` are flat array codecs importing only `_typing`, and the frames call them.
+# `Persistable` puts `save`/`load` on the frame, so the frame is what reaches the
+# serializer. ADR-002 described the inverse until its 2026-08-17 amendment (register
+# C-82); it now matches this contract.
+[[tool.importlinter.contracts]]
+name = "The leaf's internal layering runs one way"
+type = "layers"
+layers = [
+    "views_frames.feature_frame | views_frames.prediction_frame | views_frames.target_frame | views_frames.conformance",
+    "views_frames.protocols",
+    "views_frames.index",
+    "views_frames._validation | views_frames.io",
+    "views_frames._typing | views_frames.metadata | views_frames.spatial_level",
 ]
 
 [tool.hatch.build.targets.wheel]

{views_frames-1.10.2 → views_frames-2.0.0}/src/views_frames/_validation.py

@@ -22,9 +22,7 @@ from views_frames._typing import IntArray
 REQUIRED_IDENTIFIERS = ("time", "unit")
 
 
-def validate_identifiers(
-    identifiers: dict[str, IntArray], n_rows: int
-) -> None:
+def validate_identifiers(identifiers: dict[str, IntArray], n_rows: int) -> None:
     """Assert identifiers are integer 1-D arrays of length ``n_rows``, complete.
 
     Args:
@@ -42,8 +40,7 @@ def validate_identifiers(
     for key, arr in identifiers.items():
         if not isinstance(arr, np.ndarray):
             raise TypeError(
-                f"Identifier '{key}' must be a numpy array, "
-                f"got {type(arr).__name__}"
+                f"Identifier '{key}' must be a numpy array, got {type(arr).__name__}"
             )
         if not np.issubdtype(arr.dtype, np.integer):
             raise TypeError(
@@ -51,13 +48,10 @@ def validate_identifiers(
                 f"(integers cannot be NaN); got {arr.dtype}"
             )
         if arr.ndim != 1:
-            raise ValueError(
-                f"Identifier '{key}' must be 1-D, got ndim={arr.ndim}"
-            )
+            raise ValueError(f"Identifier '{key}' must be 1-D, got ndim={arr.ndim}")
         if arr.shape[0] != n_rows:
             raise ValueError(
-                f"Identifier '{key}' has length {arr.shape[0]} "
-                f"but expected {n_rows}"
+                f"Identifier '{key}' has length {arr.shape[0]} but expected {n_rows}"
             )
 
 
@@ -98,9 +92,7 @@ def validate_values(values: NDArray[np.float32]) -> None:
             an explicit trailing sample axis (``ndim < 2``).
     """
     if not isinstance(values, np.ndarray):
-        raise TypeError(
-            f"values must be a numpy array, got {type(values).__name__}"
-        )
+        raise TypeError(f"values must be a numpy array, got {type(values).__name__}")
     if values.dtype == np.dtype(object):
         raise ValueError(
             "values must not be object dtype — list-in-cell is banned (README §7)"

{views_frames-1.10.2 → 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.10.2 → 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.10.2 → 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.10.2 → views_frames-2.0.0}/src/views_frames/io/npz.py

@@ -36,7 +36,13 @@ def save(
     header: dict[str, Any] = {"level": level, "metadata": metadata}
     if feature_names is not None:
         header["feature_names"] = feature_names
-    payload = json.dumps(header, sort_keys=True, default=str)
+    # No `default=` on purpose (register C-90). It used to be `default=str`, which
+    # silently stringified a non-JSON header value — a `datetime` timestamp reloaded as
+    # "2026-01-01 00:00:00", where the field is declared `int | None`. `io/arrow` has
+    # never had it, so the same frame persisted lossily through one codec and raised
+    # through the other: the storage backend decided whether the run failed. ADR-008
+    # says fail loud, so both now raise.
+    payload = json.dumps(header, sort_keys=True)
     (directory / "header.json").write_text(payload)
 
 

{views_frames-1.10.2 → views_frames-2.0.0}/src/views_frames/metadata.py

@@ -1,9 +1,14 @@
 """`FrameMetadata` — the typed, optional-extensible provenance header (ADR-013).
 
-Not a free-form dict: a frozen dataclass with all-optional, validated fields, so
+Not a free-form dict: a frozen dataclass with all-optional, *declared* 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.
 
+The field **values** are not validated — ADR-013's as-built amendment records that
+"validated at construction" applies to the frames and identifiers, not to the header's
+own fields, and checking them here would be the semantic inference ADR-003 forbids.
+See ``docs/CICs/FrameMetadata.md`` §4.
+
 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

{views_frames-1.10.2 → 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.10.2 → 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.10.2 → views_frames-2.0.0}/src/views_frames_reconcile/conformance.py

@@ -19,6 +19,8 @@ from numpy.typing import NDArray
 from views_frames import PredictionFrame, SpatialLevel
 from views_frames_reconcile.module import ReconciliationModule
 
+__all__ = ["assert_reconcile_contract"]
+
 
 def _require_assertions() -> None:
     """Fail loud if assertions are stripped (``python -O``/``-OO``).
@@ -85,7 +87,5 @@ def assert_reconcile_contract(
         cm_total = cm_frame.values[cm_pos[(int(t), int(c))]]
         total = np.broadcast_to(cm_total, out_sum.shape)
         active = in_sum != 0
-        np.testing.assert_allclose(
-            out_sum[active], total[active], rtol=1e-4, atol=1e-3
-        )
+        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.10.2 → views_frames-2.0.0}/src/views_frames_reconcile/grouping.py

@@ -83,7 +83,7 @@ def reconcile_pgm_to_cm(
                 f"grid group (time={t}, country={c}) has no country forecast "
                 "in cm_frame"
             )
-        rows = order[bounds[gi]:bounds[gi + 1]]
+        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)

{views_frames-1.10.2 → views_frames-2.0.0}/src/views_frames_reconcile/validation.py

@@ -66,8 +66,7 @@ def validate_reconciliation_inputs(
         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)
+        (int(t), int(c)) for t, c in zip(pgm_frame.index.time, cm_units, strict=True)
     }
     have = {
         (int(t), int(c))

{views_frames-1.10.2 → views_frames-2.0.0}/src/views_frames_summarize/config.py

@@ -35,7 +35,8 @@ TOWER_CONFIG: Final[dict[str, Any]] = {
     # passes the real-cell C-44 gate with margin — the tip floor's median is safe as
     # long as a duplicate stack is under half the floor (k > 2·duplicates; at S=32,
     # k=8 tolerates the observed 2-3-zero stacks). Containment law: every HDI of mass
-    # > tip_mass/2 provably contains the tip (asserted in conformance.py).
+    # > tip_mass/2 provably contains the tip (asserted in conformance.py, which counts a
+    # floor's occupancy rather than computing it from the mass — register C-88).
     "tip_mass": 0.25,
     # Optional magnitude zero rule, OFF by default (``None``). When set to a float, a
     # row whose every draw is <= it collapses to 0 — a *count* opt-in (sub-1 ⇒ 0).

{views_frames-1.10.2 → 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
@@ -18,9 +19,11 @@ 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
-from views_frames_summarize.tower import hdi_tower
+from views_frames_summarize.tower import _in_range_span, hdi_tower
 from views_frames_summarize.tower_point import tower_point
 
+__all__ = ["assert_summarizer_contract"]
+
 
 def _require_assertions() -> None:
     """Fail loud if assertions are stripped (``python -O``/``-OO``).
@@ -42,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)
@@ -126,31 +146,76 @@ def _assert_tower_contract(frame: AnyFrame, n: int) -> None:
     assert (tip.values[..., 0] >= tlo - 1e-6).all(), "tip below the tip_mass floor"
     assert (tip.values[..., 0] <= thi + 1e-6).all(), "tip above the tip_mass floor"
 
-    # MAP-containment law (ADR-019 amendment 2026-07-24). Wider-than-tip_mass floors
-    # contain the tip by nesting. Below tip_mass, a nested floor still contains it
-    # whenever it holds MORE THAN HALF the tip floor's draws: a contiguous sub-window
-    # longer than half the parent cannot trim away the parent's middle draw(s), and
-    # the tip is their median/average. A floor of mass m spans floor(m·S)+1 draws
-    # (the `_ks` value counts inter-draw steps), so the exact condition is
-    # 2·(floor(m·S)+1) > floor(tip_mass·S)+1 — asymptotically mass > tip_mass/2.
-    # Floors below it carry NO guarantee and are below platform sample resolution
-    # (see tower_point.py / research/map_hdi/tip_mass_study.py).
-    s_count = int(frame.values.shape[-1])
-    n_tip = int(np.floor(tip_mass * s_count)) + 1
-    guaranteed = tuple(
-        float(m)
-        for m in config.canonical_floors()
-        if 2 * (int(np.floor(float(m) * s_count)) + 1) > n_tip
+    # MAP-containment law (ADR-019 amendment 2026-07-24; corrected 2026-08-18, C-88).
+    # Wider-than-tip_mass floors contain the tip by nesting. Below tip_mass, a nested
+    # floor still contains it whenever it holds MORE THAN HALF the tip floor's draws:
+    # a contiguous sub-window longer than half the parent cannot trim away the parent's
+    # middle draw(s), and the tip is their median/average.
+    #
+    # The count must be the draws whose VALUE lies in the floor — what `_in_range_span`
+    # returns and what `tower_point` takes the median of. The law originally used
+    # `floor(m·S)+1`, the *index span* `_ks` builds a floor from. Those agree only when
+    # draws are distinct: duplicated endpoint values put more draws inside the same
+    # bounds, so the tip floor held more than the formula said and narrower floors were
+    # certified that hold less than half of it. On zero-inflated integer counts — this
+    # platform's primary shape — that failed ~6% of rows, in consumers' own CI.
+    #
+    # Rows differ, so a floor may qualify in one row and not another; it is asserted
+    # only where it qualifies. Floors qualifying nowhere carry NO guarantee and sit
+    # below platform sample resolution (see tower_point.py and the tip_mass study).
+    #
+    # Only floors at or below tip_mass are candidates. A wider floor contains the tip by
+    # nesting from the tip_mass floor, which the assertion above already covers.
+    candidates = tuple(
+        float(m) for m in config.canonical_floors() if float(m) <= tip_mass
     )
-    law_tower = hdi_tower(frame, masses=guaranteed)
-    for j, m in enumerate(guaranteed):
-        glo, ghi = law_tower[..., j, 0], law_tower[..., j, 1]
-        assert (tip.values[..., 0] >= glo - 1e-6).all(), (
-            f"MAP-containment violated: tip below the {m:.2f} floor"
-        )
-        assert (tip.values[..., 0] <= ghi + 1e-6).all(), (
-            f"MAP-containment violated: tip above the {m:.2f} floor"
-        )
+    law_tower = hdi_tower(frame, masses=candidates)
+
+    # Nesting across the candidate grid, asserted UNCONDITIONALLY. Qualification is
+    # derived from `law_tower` — the output under test — so without this a broken tower
+    # could disarm the law with its own defect: degenerate narrow floors give a small
+    # in-range count, fail `2·n_floor > n_tip`, and skip themselves. Nesting needs no
+    # qualification (it is true by construction), so it keeps the teeth.
+    lo_grid, hi_grid = law_tower[..., 0], law_tower[..., 1]
+    assert (np.diff(lo_grid, axis=-1) <= 1e-6).all(), (
+        "sub-tip_mass floors must nest: lowers non-increasing"
+    )
+    assert (np.diff(hi_grid, axis=-1) >= -1e-6).all(), (
+        "sub-tip_mass floors must nest: uppers non-decreasing"
+    )
+
+    # Counted block-wise, in the same row blocks `hdi_tower` uses. The published suite
+    # must stay inside the memory discipline of the code it certifies (C-22/C-25/C-71):
+    # sorting the whole grid at once would allocate a full copy of a 1M×1000 frame.
+    #
+    # A `zero_cutoff` row (C-45) collapses to (0, 0) in both tower and tip, so its
+    # in-range counts are 0, nothing qualifies, and the row is skipped — correctly:
+    # containment of tip 0 in floor (0, 0) is trivially true there.
+    s_count = int(frame.values.shape[-1])
+    flat = np.ascontiguousarray(frame.values).reshape(-1, s_count)
+    flat_lo = lo_grid.reshape(-1, len(candidates))
+    flat_hi = hi_grid.reshape(-1, len(candidates))
+    flat_tip = np.ravel(tip.values[..., 0])
+    tip_lo, tip_hi = np.ravel(tlo), np.ravel(thi)
+    block_rows = int(config.get("row_block"))
+
+    for start in range(0, flat.shape[0], block_rows):
+        stop = min(start + block_rows, flat.shape[0])
+        srt = np.sort(flat[start:stop], axis=-1)
+        _, n_tip = _in_range_span(srt, tip_lo[start:stop], tip_hi[start:stop])
+        for j, m in enumerate(candidates):
+            glo, ghi = flat_lo[start:stop, j], flat_hi[start:stop, j]
+            _, n_floor = _in_range_span(srt, glo, ghi)
+            qualifies = 2 * n_floor > n_tip
+            if not qualifies.any():
+                continue
+            tips = flat_tip[start:stop]
+            assert (tips[qualifies] >= glo[qualifies] - 1e-6).all(), (
+                f"MAP-containment violated: tip below the {m:.2f} floor"
+            )
+            assert (tips[qualifies] <= ghi[qualifies] + 1e-6).all(), (
+                f"MAP-containment violated: tip above the {m:.2f} floor"
+            )
 
     # Reproducibility law: the 50% HDI is independent of the other requested masses.
     just_50 = hdi_tower(frame, masses=(0.5,))

{views_frames-1.10.2 → 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 —

{views_frames-1.10.2 → views_frames-2.0.0}/src/views_frames_summarize/tower_point.py

@@ -7,6 +7,7 @@ amendment 2026-07-24, evidence in `research/map_hdi/tip_mass_study.py`). Zero-in
 is handled by that floor's density (a zero-majority row reads 0); the optional,
 off-by-default magnitude cutoff applies too if set (C-45). Containment law: every HDI
 whose floor holds more than half the tip floor's draws provably contains the tip
+(occupancy counted from the draws in range, not computed from the mass — register C-88)
 (asymptotically, mass > `tip_mass`/2 — a nested contiguous window longer than half
 the parent cannot trim away the parent's median); narrower floors carry no guarantee
 and are below platform sample resolution. Asserted in ``conformance.py``.