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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: views-frames
-Version: 1.7.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
@@ -22,6 +22,12 @@ Requires-Python: >=3.10
 Requires-Dist: numpy<3,>=1.26
 Provides-Extra: arrow
 Requires-Dist: pyarrow<20,>=14; extra == 'arrow'
+Provides-Extra: docs
+Requires-Dist: jupyterlab<5,>=4; extra == 'docs'
+Requires-Dist: matplotlib<4,>=3.8; extra == 'docs'
+Requires-Dist: nbmake<2,>=1.5; extra == 'docs'
+Requires-Dist: pyarrow<20,>=14; extra == 'docs'
+Requires-Dist: scipy<2,>=1.11; extra == 'docs'
 Description-Content-Type: text/markdown
 
 # views-frames
@@ -30,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
@@ -249,7 +259,13 @@ 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.) **Copy-vs-view:** structural and
+   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
    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.7.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
@@ -223,7 +227,13 @@ 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.) **Copy-vs-view:** structural and
+   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
    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.7.0 → views_frames-1.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "views-frames"
-version = "1.7.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" },
@@ -39,6 +39,22 @@ Changelog = "https://github.com/views-platform/views-frames/blob/main/CHANGELOG.
 # Optional serialization extra — pyarrow is allowed ONLY behind io/ (README §3.1).
 [project.optional-dependencies]
 arrow = ["pyarrow>=14,<20"]
+# Optional docs/notebooks extra — plotting + jupyter for the showcase notebooks
+# (notebooks/, an un-gated dev artifact outside src/). NEVER runtime dependencies;
+# self-references [arrow] so `uv sync --extra docs` also enables the parquet round-trip
+# demo in notebooks/01_frames.ipynb. matplotlib/scipy are notebook-only (the core is
+# numpy-only); these are imported by notebooks, never by the package.
+docs = [
+    "views-frames[arrow]",
+    "matplotlib>=3.8,<4",
+    "scipy>=1.11,<2",
+    "jupyterlab>=4,<5",
+    # nbmake drives the non-blocking notebook-execution CI check (issue #151): it just
+    # runs the notebooks end-to-end to catch frozen-API drift. A test tool, but it rides
+    # in [docs] so the single `uv sync --extra docs` provisions everything the notebooks
+    # job needs (kernel + plotting + the checker).
+    "nbmake>=1.5,<2",
+]
 
 [dependency-groups]
 dev = [
@@ -76,9 +92,10 @@ show_missing = true
 [tool.ruff]
 line-length = 88
 target-version = "py310"
-# research/ is the volatile estimator lab (outside the frozen, gated src/); it is
-# not held to the leaf's lint/format bar.
-extend-exclude = ["research"]
+# research/ is the volatile estimator lab and notebooks/ holds the un-gated showcase
+# notebooks + their helper (notebooks/_synthetic.py) — both sit outside the frozen,
+# gated src/ and are not held to the leaf's lint/format bar.
+extend-exclude = ["research", "notebooks"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "UP", "B", "A", "C4", "SIM"]
@@ -87,11 +104,13 @@ 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.
+# The reconciliation parity tests 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"]
+# The dev/ops scripts (oracle regeneration; the reconciliation parity verifier) are not
+# CI-run and carry dense numpy one-liners + report f-strings; not held to the wrap bar.
+"scripts/*.py" = ["E501"]
 
 [tool.mypy]
 python_version = "3.10"

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

@@ -7,5 +7,18 @@ 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
+from views_frames_reconcile.result import (
+    ALIGNED_DRAWS,
+    METHOD_PROPORTIONAL,
+    POINT_BROADCAST,
+    ReconciliationResult,
+)
 
-__all__ = ["ReconciliationModule", "reconcile_proportional"]
+__all__ = [
+    "ALIGNED_DRAWS",
+    "METHOD_PROPORTIONAL",
+    "POINT_BROADCAST",
+    "ReconciliationModule",
+    "ReconciliationResult",
+    "reconcile_proportional",
+]

{views_frames-1.7.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)
@@ -66,7 +80,10 @@ def assert_reconcile_contract(
         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,)
+        # cm may be a point (sample_count == 1, broadcast inside reconcile) or aligned
+        # draws — broadcast its per-(time, country) total to the draw axis either way.
+        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

views_frames-1.8.1/src/views_frames_reconcile/module.py

@@ -0,0 +1,120 @@
+"""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.result import (
+    ALIGNED_DRAWS,
+    METHOD_PROPORTIONAL,
+    POINT_BROADCAST,
+    ReconciliationResult,
+)
+from views_frames_reconcile.validation import validate_reconciliation_inputs
+
+
+def _broadcast_point_country(
+    cm_frame: PredictionFrame, n_samples: int
+) -> PredictionFrame:
+    """Tile a point country forecast (``sample_count == 1``) across ``n_samples`` draws.
+
+    Bit-identical to the WET broadcast pipeline-core's ``align_country_to_grid`` does
+    (views-frames#143): the single column is repeated, so every draw is rescaled to the
+    same total. It lives in the orchestrator so the leaf ``proportional`` and the
+    parity-frozen ``grouping`` hot loop stay **untouched** — the equal-count path is
+    byte-for-byte identical and only ``sample_count == 1`` takes this new path.
+    """
+    tiled = np.tile(np.asarray(cm_frame.values, dtype=np.float32), (1, n_samples))
+    return PredictionFrame(tiled, cm_frame.index, cm_frame.metadata)
+
+
+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_result(
+        self, cm_frame: PredictionFrame, pgm_frame: PredictionFrame
+    ) -> ReconciliationResult:
+        """Reconcile, also reporting the mode — a ``ReconciliationResult``.
+
+        A **point** country (``cm.sample_count == 1``) is broadcast across the grid's
+        draws before reconciling (mode ``point-broadcast``); an **aligned** country
+        (``cm.sample_count == S``) scales draw-for-draw (mode ``aligned-draws``, the
+        documented per-draw approximation). Any other count fails loud.
+
+        The mode is **returned**, never stamped on the leaf's generic ``FrameMetadata``
+        (ADR-020 / register C-47 — the leaf carries no reconciliation vocabulary; see
+        ``result.py``).
+
+        Raises:
+            ValueError: the inputs fail validation (level / sample-count — cm must be 1
+                or pgm's ``S`` / time coverage / missing country forecast).
+        """
+        validate_reconciliation_inputs(
+            cm_frame, pgm_frame, self._map_keys, self._map_vals
+        )
+        if cm_frame.sample_count != pgm_frame.sample_count:
+            cm = _broadcast_point_country(cm_frame, pgm_frame.sample_count)
+            mode = POINT_BROADCAST
+        else:
+            cm = cm_frame
+            mode = ALIGNED_DRAWS
+        frame = reconcile_pgm_to_cm(pgm_frame, cm, self._map_keys, self._map_vals)
+        return ReconciliationResult(frame=frame, mode=mode, method=METHOD_PROPORTIONAL)
+
+    def reconcile(
+        self, cm_frame: PredictionFrame, pgm_frame: PredictionFrame
+    ) -> PredictionFrame:
+        """Validate the inputs, then return a new pgm frame reconciled to cm totals.
+
+        Point/aligned handling and fail-loud are as :meth:`reconcile_result`; this
+        returns only the reconciled frame. Call :meth:`reconcile_result` when you also
+        need the reconciliation *mode* (point-broadcast vs aligned-draws).
+
+        Raises:
+            ValueError: the inputs fail validation (level / sample-count — cm must be 1
+                or pgm's ``S`` / time coverage / missing country forecast).
+        """
+        return self.reconcile_result(cm_frame, pgm_frame).frame

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

@@ -9,10 +9,18 @@ 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
-tracked as **C-37** and is deliberately deferred until this port's parity with
-the original is proven and the move is wired.
+principled joint probabilistic reconciliation. The upgrade to the latter is designed
+in **ADR-024** (register **C-62**; the cross-repo lineage is views-postprocessing
+C-37) and is deliberately **deferred**: per-draw pairing of independently-trained
+grid and country draws has no shared draw identity, so the principled method waits on
+a defined draw-identity/coupling contract and a consumer that needs calibrated joint
+tails.
 
 No torch, no pandas — numpy only.
 """
@@ -24,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,
@@ -46,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
@@ -62,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.1/src/views_frames_reconcile/result.py

@@ -0,0 +1,55 @@
+"""The reconciliation result — the reconciled frame plus *how* it was produced (#144).
+
+The reconciliation **mode** (`point-broadcast` vs `aligned-draws`) and **method** are
+reported here, on a reconcile-package result object — deliberately **not** stamped onto
+the leaf's generic ``FrameMetadata``. That header is governed *generic-only* (ADR-020 /
+register C-47): the numpy leaf carries provenance meaningful for *any* frame (`run_id`,
+`data_version`) and must never carry domain/operation vocabulary it cannot know — as
+evaluation provenance lives in views-evaluation's ``MetricFrame``, not the leaf.
+Reconciliation is a sibling operation, so its provenance is reported by the sibling.
+
+A caller that needs the mode reads it off :class:`ReconciliationResult`
+(``ReconciliationModule.reconcile_result``); a caller that only needs the frame uses
+``ReconciliationModule.reconcile``, which returns the frame directly.
+
+The mode reflects **what this reconcile call did** (broadcast a point, or scaled aligned
+draws) — not upstream provenance: a caller that pre-tiles a point country to ``S`` draws
+before calling reconciles in ``aligned-draws`` mode. The string values match
+pipeline-core's ``reconcile_frames`` constants verbatim, so the *vocabulary* is shared
+across the repos that produce and consume the mode.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from views_frames import PredictionFrame
+
+#: Mode — the call **broadcast a point**: the country arrived as a point
+#: (``cm.sample_count == 1``) against a multi-draw grid and was tiled across the grid's
+#: ``S`` draws (every draw rescaled to the same total).
+POINT_BROADCAST = "point-broadcast"
+#: Mode — the call **scaled aligned draws**: the country already carried the grid's draw
+#: count (``cm.sample_count == S``) and was scaled draw-for-draw — the per-draw
+#: approximation (the principled joint upgrade is a separate design, #145). The mode
+#: describes *what this call did*: a point against a single-draw grid, or a point the
+#: caller pre-tiled to ``S``, also reads as aligned-draws (nothing was broadcast).
+ALIGNED_DRAWS = "aligned-draws"
+#: The reconciliation algorithm — top-down proportional, per draw.
+METHOD_PROPORTIONAL = "proportional"
+
+
+@dataclass(frozen=True)
+class ReconciliationResult:
+    """A reconciled grid frame plus how it was produced.
+
+    Attributes:
+        frame: the reconciled pgm ``PredictionFrame`` (identical to what ``reconcile``
+            returns).
+        mode: :data:`POINT_BROADCAST` or :data:`ALIGNED_DRAWS`.
+        method: the reconciliation method, e.g. :data:`METHOD_PROPORTIONAL`.
+    """
+
+    frame: PredictionFrame
+    mode: str
+    method: str

{views_frames-1.7.0 → views_frames-1.8.1}/src/views_frames_reconcile/validation.py

@@ -6,7 +6,8 @@ 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`
+  - (per-draw scaling needs it)     -> equal `sample_count`, or a point cm
+                                       (`sample_count == 1`) broadcast across the draws
   - valid countries                 -> every (time, country) the grid maps to has
                                        a country forecast in the cm frame
 
@@ -44,10 +45,11 @@ def validate_reconciliation_inputs(
         raise ValueError(
             f"grid frame must be at SpatialLevel.PGM, got {pgm_frame.index.level}"
         )
-    if cm_frame.sample_count != pgm_frame.sample_count:
+    if cm_frame.sample_count not in (1, pgm_frame.sample_count):
         raise ValueError(
-            f"sample-count mismatch: cm has {cm_frame.sample_count}, "
-            f"pgm has {pgm_frame.sample_count}"
+            f"sample-count mismatch: cm has {cm_frame.sample_count}, pgm has "
+            f"{pgm_frame.sample_count}; cm must be 1 (point, broadcast across draws) "
+            f"or {pgm_frame.sample_count} (aligned draws)"
         )
 
     cm_times = {int(t) for t in np.unique(cm_frame.index.time)}

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

views_frames-1.7.0/src/views_frames_reconcile/module.py

@@ -1,68 +0,0 @@
-"""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)