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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: views-frames
-Version: 2.0.0
+Version: 3.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,11 +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:** **v2.0.0 — the version in this tree.** For what is actually published, see
+> **Status:** **v3.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
+> a publication it cannot verify. API frozen at v1.0.0 (ADR-018) and broken twice since, in 2.0.0
+> (ADR-028) and 3.0.0 (ADR-030; 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
@@ -57,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; **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
+> 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; **v3.0.0 is the second MAJOR** — reconciliation silently lost a country's fatalities whenever its grid was all zeros in a draw, 2.9–7.3% of the fatality mass on the first production run (#283, register C-99); such a draw now borrows the pattern of a random donor draw from the same month and country, a group with no donor raises, every other draw is bit-identical, and `CONFORMANCE_FLOOR` moves to `3.0.0`, ADR-030). 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
@@ -472,12 +472,13 @@ views-frames/
 │   ├── __init__.py                #   depends on views_frames + numpy only; never the reverse
 │   ├── proportional.py            # reconcile_proportional — per-draw top-down scaling
 │   ├── grouping.py                # reconcile_pgm_to_cm — group by (time, country)
+│   ├── donor_fill.py              # empty grid draw → a donor draw's pattern (ADR-030)
 │   ├── 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
-├── scripts/                       # standalone dev tools, none wired into CI
+├── scripts/                       # dev tools; check_arch_tree + check_doc_refs run in CI
 ├── examples/                      # runnable quickstarts (run by CI)
 └── tests/                         # flat: test_*.py + fixtures/
 ```
@@ -524,12 +525,22 @@ from views_frames_reconcile import ReconciliationModule
 
 # mapping is INJECTED by the caller (sourced from the producer; never fetched here):
 #   map_keys: (M, 2) int (time, priogrid_gid)   map_vals: (M,) int country_id
-reconciler = ReconciliationModule(map_keys, map_vals)
+reconciler = ReconciliationModule(map_keys, map_vals, seed=0)
 pgm_reconciled = reconciler.reconcile(cm_frame, pgm_frame)  # new pgm PredictionFrame
-# each (time, country) group's cells now sum, per draw, to the country total
-# (all-zero grid draws stay zero); zeros preserved; non-negative.
+# each (time, country) group's cells now sum, in EVERY draw, to the country total;
+# zeros preserved in draws that had grid mass; non-negative.
 ```
 
+**The country forecast is the authority — in every draw (3.0.0, ADR-030).** Scaling
+cannot place a positive country value on a draw whose grid cells are all zero. Until
+3.0.0 that draw stayed zero and the country's fatalities were silently missing from the
+grid: 2.9–7.3% of the fatality mass on the first production run (#283). Now such a draw
+borrows the pattern of a **donor** — a draw of the same `(time, country)` that has grid
+mass, chosen at random from `default_rng([seed, time, country])` — and is scaled like any
+other. The country decides how many; the grid model's own draws decide where. A group in
+which **no** draw has grid mass raises `ValueError` instead of returning a grid short of
+the country. `reconcile_result(...).filled_draws` reports how many draws were filled.
+
 > **Future DRY pass (deferred).** `grouping.py` labels grid rows by country with the
 > leaf's `cross_level_align_arrays` and overlaps `cross_level_align` (index.py). Folding
 > the two is a separate later story — the v1.7.0 relocation is a faithful **WET** move,

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

@@ -4,11 +4,11 @@
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **v2.0.0 — the version in this tree.** For what is actually published, see
+> **Status:** **v3.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
+> a publication it cannot verify. API frozen at v1.0.0 (ADR-018) and broken twice since, in 2.0.0
+> (ADR-028) and 3.0.0 (ADR-030; 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
@@ -25,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; **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
+> 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; **v3.0.0 is the second MAJOR** — reconciliation silently lost a country's fatalities whenever its grid was all zeros in a draw, 2.9–7.3% of the fatality mass on the first production run (#283, register C-99); such a draw now borrows the pattern of a random donor draw from the same month and country, a group with no donor raises, every other draw is bit-identical, and `CONFORMANCE_FLOOR` moves to `3.0.0`, ADR-030). 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
@@ -440,12 +440,13 @@ views-frames/
 │   ├── __init__.py                #   depends on views_frames + numpy only; never the reverse
 │   ├── proportional.py            # reconcile_proportional — per-draw top-down scaling
 │   ├── grouping.py                # reconcile_pgm_to_cm — group by (time, country)
+│   ├── donor_fill.py              # empty grid draw → a donor draw's pattern (ADR-030)
 │   ├── 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
-├── scripts/                       # standalone dev tools, none wired into CI
+├── scripts/                       # dev tools; check_arch_tree + check_doc_refs run in CI
 ├── examples/                      # runnable quickstarts (run by CI)
 └── tests/                         # flat: test_*.py + fixtures/
 ```
@@ -492,12 +493,22 @@ from views_frames_reconcile import ReconciliationModule
 
 # mapping is INJECTED by the caller (sourced from the producer; never fetched here):
 #   map_keys: (M, 2) int (time, priogrid_gid)   map_vals: (M,) int country_id
-reconciler = ReconciliationModule(map_keys, map_vals)
+reconciler = ReconciliationModule(map_keys, map_vals, seed=0)
 pgm_reconciled = reconciler.reconcile(cm_frame, pgm_frame)  # new pgm PredictionFrame
-# each (time, country) group's cells now sum, per draw, to the country total
-# (all-zero grid draws stay zero); zeros preserved; non-negative.
+# each (time, country) group's cells now sum, in EVERY draw, to the country total;
+# zeros preserved in draws that had grid mass; non-negative.
 ```
 
+**The country forecast is the authority — in every draw (3.0.0, ADR-030).** Scaling
+cannot place a positive country value on a draw whose grid cells are all zero. Until
+3.0.0 that draw stayed zero and the country's fatalities were silently missing from the
+grid: 2.9–7.3% of the fatality mass on the first production run (#283). Now such a draw
+borrows the pattern of a **donor** — a draw of the same `(time, country)` that has grid
+mass, chosen at random from `default_rng([seed, time, country])` — and is scaled like any
+other. The country decides how many; the grid model's own draws decide where. A group in
+which **no** draw has grid mass raises `ValueError` instead of returning a grid short of
+the country. `reconcile_result(...).filled_draws` reports how many draws were filled.
+
 > **Future DRY pass (deferred).** `grouping.py` labels grid rows by country with the
 > leaf's `cross_level_align_arrays` and overlaps `cross_level_align` (index.py). Folding
 > the two is a separate later story — the v1.7.0 relocation is a faithful **WET** move,

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

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

@@ -19,8 +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. It moved to ``2.0.0`` with the 2.0.0 MAJOR (ADR-028) — the first
-move since the v1.0.0 freeze.
+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, and to ``3.0.0`` with the 3.0.0 MAJOR (ADR-030).
 """
 
 from __future__ import annotations
@@ -30,11 +30,12 @@ from typing import Any
 
 import numpy as np
 
-# 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"
+# Bumped to 3.0.0 for the 3.0.0 MAJOR (ADR-030): `assert_reconcile_contract` now
+# requires every draw to sum to its country, where it used to require draws with an
+# empty grid to stay zero. GOVERNANCE bumps the floor on any breaking change to any
+# published entry point (the 2.0.0 move, ADR-028, was the first since the freeze). A
+# consumer reading this learns which contract its CI asserts.
+CONFORMANCE_FLOOR = "3.0.0"
 
 __all__ = [
     "CONFORMANCE_FLOOR",

{views_frames-2.0.0 → views_frames-3.0.0}/src/views_frames_reconcile/__init__.py

@@ -1,14 +1,18 @@
 """Forecast reconciliation (pgm forecasts reconciled to cm totals).
 
 Slice 1 ports the top-down proportional method from views-reporting as a pure
-numpy function. New methods (e.g. principled probabilistic reconciliation, C-37)
-should be added as sibling modules, not by modifying ``proportional``.
+numpy function. Since 3.0.0 a draw whose grid is empty but whose country is
+positive first borrows a donor draw's pattern (``donor_fill``, ADR-030), so every
+draw sums to its country. New methods (e.g. principled probabilistic
+reconciliation, C-37) 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_DONOR_FILL,
     METHOD_PROPORTIONAL,
     POINT_BROADCAST,
     ReconciliationResult,
@@ -16,6 +20,7 @@ from views_frames_reconcile.result import (
 
 __all__ = [
     "ALIGNED_DRAWS",
+    "METHOD_DONOR_FILL",
     "METHOD_PROPORTIONAL",
     "POINT_BROADCAST",
     "ReconciliationModule",

{views_frames-2.0.0 → views_frames-3.0.0}/src/views_frames_reconcile/conformance.py

@@ -1,10 +1,15 @@
 """Conformance checks for the reconcile package (ADR-023).
 
 A consumer can re-run these against its own frame factories to confirm the reconciler
-behaves: grid (``pgm``) predictions sum, per draw, to their country (``cm``) totals
-(except all-zero grid draws, which stay zero — the documented edge); zeros preserved;
-values stay non-negative; the output is a same-shape ``pgm`` ``PredictionFrame`` at PGM
-level; and the cm/pgm mapping is **injected, never fetched** (ADR-014/ADR-023).
+behaves: grid (``pgm``) predictions sum, in **every** draw, to their country (``cm``)
+totals (ADR-030: a draw whose grid was empty is filled from a donor draw of its group);
+zero cells stay zero in draws that had grid mass, and a filled draw copies a donor's
+pattern; values stay non-negative; the output is a same-shape ``pgm``
+``PredictionFrame`` at PGM level; and the cm/pgm mapping is **injected, never fetched**
+(ADR-014/ADR-023).
+
+Until 3.0.0 the sum law exempted draws whose grid was all zeros and required them to
+stay zero. That exemption is where the reconciler lost country mass (#283); it is gone.
 
 Mirrors ``views_frames_summarize/conformance.py:assert_summarizer_contract``.
 """
@@ -65,11 +70,7 @@ def assert_reconcile_contract(
     # 2. Non-negativity.
     assert bool((out.values >= 0).all()), "reconciled forecasts must be non-negative"
 
-    # 3. Zero-preservation: an input zero cell stays zero.
-    assert bool((out.values[pgm_frame.values == 0] == 0).all()), "zeros preserved"
-
-    # 4. Sum-to-country per draw: each (time, country) group's cells sum, per draw, to
-    #    its country total — except all-zero input draws, which stay zero (the edge).
+    # 3 + 4, per (time, country) group.
     cm_units = pgm_frame.index.cross_level_align_arrays(mk, mv, SpatialLevel.CM).unit
     pg_time = pgm_frame.index.time
     cm_pos = {
@@ -80,12 +81,34 @@ def assert_reconcile_contract(
     }
     for t, c in np.unique(np.stack([pg_time, cm_units], axis=1), axis=0):
         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,)
+        grid_in = np.asarray(pgm_frame.values[rows], dtype=np.float64)  # (n, S)
+        grid_out = np.asarray(out.values[rows], dtype=np.float64)
+        out_sum = grid_out.sum(axis=0)  # (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)
-        assert bool((out_sum[~active] == 0).all()), "all-zero draws stay zero"
+
+        # 4. Sum-to-country in every draw: a positive country value is placed in full,
+        #    a zero one empties the grid. No draw is exempt (ADR-030).
+        np.testing.assert_allclose(out_sum, total, rtol=1e-4, atol=1e-3)
+
+        # 3a. Zero-preservation in draws that had grid mass: their zero cells stay zero.
+        positive_in = np.where(grid_in > 0, grid_in, 0.0)
+        had_mass = positive_in.sum(axis=0) > 0
+        stays_zero = positive_in[:, had_mass] == 0
+        assert bool((grid_out[:, had_mass][stays_zero] == 0).all()), "zeros preserved"
+
+        # 3b. A filled draw (input grid empty, mass placed) is a scaled copy of a draw
+        #     of the same group that had grid mass: same zero cells, same shares.
+        filled = np.flatnonzero(~had_mass & (out_sum > 0))
+        if filled.size:
+            donors = positive_in[:, had_mass]
+            assert donors.shape[1] > 0, "a draw was filled although no draw had mass"
+            donor_shares = donors / donors.sum(axis=0)
+            for s in filled:
+                share = grid_out[:, s] / out_sum[s]
+                close = np.isclose(donor_shares, share[:, None], rtol=1e-4, atol=1e-6)
+                assert bool(close.all(axis=0).any()), (
+                    "a filled draw must copy the pattern of a donor draw of its group"
+                )

views_frames-3.0.0/src/views_frames_reconcile/donor_fill.py

@@ -0,0 +1,133 @@
+"""Donor fill: give an empty grid draw a pattern before it is scaled (ADR-030).
+
+Scaling is multiplication, so ``reconcile_proportional`` cannot place a positive
+country value on a draw whose grid cells are all zero. Before 3.0.0 that draw stayed
+zero and the country's mass was lost (2.9–7.3% on the first production run, #283).
+
+This pass runs **before** the unchanged scaling. Within each ``(time, country)`` group,
+a draw that **needs filling** (country value > 0, no grid cell > 0) receives a copy of
+the grid values of a **donor**: a draw of the same group that has grid mass, chosen
+uniformly at random. The scaling then rescales it to the draw's own country value, so
+the filled draw has exactly the donor's zero cells and proportions.
+
+The random choice is reproducible: each group draws from
+``numpy.random.default_rng([seed, time, country])``, so the result does not depend on
+how a caller chunks its calls or on group order.
+
+``proportional`` and ``grouping`` are not touched (CIC §11). The group-by-sort below
+repeats ``grouping``'s on purpose (ADR-030 §Decision 6).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames import PredictionFrame, SpatialLevel
+
+
+def fill_empty_draws(
+    grid: NDArray[np.floating[Any]],
+    country: NDArray[np.floating[Any]],
+    rng: np.random.Generator,
+) -> tuple[NDArray[np.floating[Any]], int]:
+    """Fill the draws of one group whose grid is empty but whose country is positive.
+
+    Args:
+        grid: ``(S, n_cells)`` grid values of one ``(time, country)`` group.
+        country: ``(S,)`` the country value of each draw.
+        rng: the group's generator.
+
+    Returns:
+        ``(grid, n_filled)``. ``grid`` is the input object itself when nothing needed
+        filling, otherwise a new array; the input is never modified.
+
+    Raises:
+        ValueError: a draw needs filling but no draw of the group has grid mass, so
+            there is no pattern to borrow (ADR-030 §Decision 5).
+    """
+    has_mass = (grid > 0).any(axis=1)  # (S,)
+    needs_fill = (country > 0) & ~has_mass
+    n_filled = int(needs_fill.sum())
+    if n_filled == 0:
+        return grid, 0
+    donors = np.flatnonzero(has_mass)
+    if donors.size == 0:
+        raise ValueError(
+            f"cannot place the country value of {n_filled} of {grid.shape[0]} "
+            "draw(s): the grid is zero in every cell of every draw, so there is no "
+            "donor pattern to borrow. The country forecast has fatalities where the "
+            "grid forecast has none at all (ADR-030)."
+        )
+    filled = np.array(grid, copy=True)
+    filled[needs_fill] = grid[rng.choice(donors, size=n_filled)]
+    return filled, n_filled
+
+
+def fill_empty_grid_draws(
+    pgm_frame: PredictionFrame,
+    cm_frame: PredictionFrame,
+    map_keys: NDArray[np.integer[Any]],
+    map_vals: NDArray[np.integer[Any]],
+    seed: int,
+) -> tuple[PredictionFrame, int]:
+    """Apply :func:`fill_empty_draws` to every ``(time, country)`` group of a pgm frame.
+
+    ``cm_frame`` must already carry the grid's draw count (a point country is broadcast
+    before this is called), and every grid group must have a country row
+    (``validate_reconciliation_inputs`` guarantees both).
+
+    Returns:
+        ``(frame, n_filled)``: ``pgm_frame`` itself when nothing needed filling,
+        otherwise a new frame with the same index and metadata; and the number of draws
+        filled.
+
+    Raises:
+        ValueError: a ``(time, country)`` group needs filling and has no donor. Raised
+            before any output is returned; the message names the time and country.
+    """
+    cm_units = pgm_frame.index.cross_level_align_arrays(
+        map_keys, map_vals, SpatialLevel.CM
+    ).unit
+    pg_time = pgm_frame.index.time
+    cm_vals = cm_frame.values
+    cm_pos = {
+        (int(t), int(u)): j
+        for j, (t, u) in enumerate(
+            zip(cm_frame.index.time, cm_frame.index.unit, strict=True)
+        )
+    }
+
+    pg_vals = pgm_frame.values
+    groups, inverse, counts = np.unique(
+        np.stack([pg_time, cm_units], axis=1),
+        axis=0,
+        return_inverse=True,
+        return_counts=True,
+    )
+    order = np.argsort(np.asarray(inverse).reshape(-1), kind="stable")
+    bounds = np.concatenate(([0], np.cumsum(counts)))
+
+    out: NDArray[Any] | None = None
+    n_filled = 0
+    for gi in range(groups.shape[0]):
+        t, c = int(groups[gi, 0]), int(groups[gi, 1])
+        rows = order[bounds[gi] : bounds[gi + 1]]
+        grid = pg_vals[rows].T  # (S, n_cells)
+        try:
+            filled, n = fill_empty_draws(
+                grid, cm_vals[cm_pos[(t, c)]], np.random.default_rng([seed, t, c])
+            )
+        except ValueError as err:
+            raise ValueError(f"time {t}, country {c}: {err}") from err
+        if n:
+            if out is None:
+                out = np.array(pg_vals, copy=True)
+            out[rows] = filled.T
+            n_filled += n
+
+    if out is None:
+        return pgm_frame, 0
+    return PredictionFrame(out, pgm_frame.index, pgm_frame.metadata), n_filled

{views_frames-2.0.0 → views_frames-3.0.0}/src/views_frames_reconcile/module.py

@@ -2,12 +2,14 @@
 
 `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).
+applies it: `reconcile(cm_frame, pgm_frame)` validates the inputs, gives every draw
+whose grid is empty but whose country is positive a donor draw's pattern (ADR-030),
+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
+grouping is `grouping`, the empty-draw fill is `donor_fill`, 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
@@ -22,10 +24,11 @@ import numpy as np
 from numpy.typing import NDArray
 
 from views_frames import PredictionFrame
+from views_frames_reconcile.donor_fill import fill_empty_grid_draws
 from views_frames_reconcile.grouping import reconcile_pgm_to_cm
 from views_frames_reconcile.result import (
     ALIGNED_DRAWS,
-    METHOD_PROPORTIONAL,
+    METHOD_DONOR_FILL,
     POINT_BROADCAST,
     ReconciliationResult,
 )
@@ -54,16 +57,22 @@ class ReconciliationModule:
         self,
         map_keys: NDArray[np.integer[Any]] | object,
         map_vals: NDArray[np.integer[Any]] | object,
+        *,
+        seed: int = 0,
     ) -> 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.
+            seed: non-negative int; seeds the donor choice for draws whose grid is empty
+                (ADR-030). Group ``(time, country)`` draws from
+                ``default_rng([seed, time, country])``, so the same inputs and seed give
+                the same output however the calls are chunked.
 
         Raises:
-            ValueError: ``map_keys`` is not ``(M, 2)`` or ``map_vals`` is not
-                length ``M``.
+            ValueError: ``map_keys`` is not ``(M, 2)``, ``map_vals`` is not length
+                ``M``, or ``seed`` is not a non-negative int.
         """
         keys = np.asarray(map_keys)
         vals = np.asarray(map_vals)
@@ -71,8 +80,12 @@ class ReconciliationModule:
             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")
+        is_int = isinstance(seed, (int, np.integer)) and not isinstance(seed, bool)
+        if not is_int or seed < 0:
+            raise ValueError(f"seed must be a non-negative int, got {seed!r}")
         self._map_keys = keys
         self._map_vals = vals
+        self._seed = int(seed)
 
     def reconcile_result(
         self, cm_frame: PredictionFrame, pgm_frame: PredictionFrame
@@ -90,7 +103,9 @@ class ReconciliationModule:
 
         Raises:
             ValueError: the inputs fail validation (level / sample-count — cm must be 1
-                or pgm's ``S`` / time coverage / missing country forecast).
+                or pgm's ``S`` / time coverage / missing country forecast), or a
+                ``(time, country)`` has a positive country value in a draw whose grid is
+                empty and no draw of that group has grid mass to borrow (ADR-030).
         """
         validate_reconciliation_inputs(
             cm_frame, pgm_frame, self._map_keys, self._map_vals
@@ -101,8 +116,13 @@ class ReconciliationModule:
         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)
+        filled, filled_draws = fill_empty_grid_draws(
+            pgm_frame, cm, self._map_keys, self._map_vals, self._seed
+        )
+        frame = reconcile_pgm_to_cm(filled, cm, self._map_keys, self._map_vals)
+        return ReconciliationResult(
+            frame=frame, mode=mode, method=METHOD_DONOR_FILL, filled_draws=filled_draws
+        )
 
     def reconcile(
         self, cm_frame: PredictionFrame, pgm_frame: PredictionFrame
@@ -115,6 +135,8 @@ class ReconciliationModule:
 
         Raises:
             ValueError: the inputs fail validation (level / sample-count — cm must be 1
-                or pgm's ``S`` / time coverage / missing country forecast).
+                or pgm's ``S`` / time coverage / missing country forecast), or a
+                ``(time, country)`` has a positive country value in a draw whose grid is
+                empty and no draw of that group has grid mass to borrow (ADR-030).
         """
         return self.reconcile_result(cm_frame, pgm_frame).frame

{views_frames-2.0.0 → views_frames-3.0.0}/src/views_frames_reconcile/result.py

@@ -31,12 +31,19 @@ from views_frames import PredictionFrame
 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).
+#: approximation (the principled joint upgrade is designed and deferred, ADR-024 /
+#: register C-62). 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.
+#: The 2.x reconciliation algorithm — top-down proportional, per draw. No longer what
+#: ``ReconciliationModule`` reports (see :data:`METHOD_DONOR_FILL`); kept because it is
+#: frozen public surface (ADR-018).
 METHOD_PROPORTIONAL = "proportional"
+#: The reconciliation algorithm since 3.0.0 — top-down proportional, per draw, after a
+#: draw whose grid is empty but whose country is positive borrows a donor draw's pattern
+#: (ADR-030).
+METHOD_DONOR_FILL = "proportional-donor-fill"
 
 
 @dataclass(frozen=True)
@@ -47,9 +54,12 @@ class ReconciliationResult:
         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`.
+        method: the reconciliation method, e.g. :data:`METHOD_DONOR_FILL`.
+        filled_draws: how many ``(time, country, draw)`` draws had an empty grid and a
+            positive country value, and were given a donor draw's pattern (ADR-030).
     """
 
     frame: PredictionFrame
     mode: str
     method: str
+    filled_draws: int = 0