views-frames 1.0.0__tar.gz → 1.1.1__tar.gz

views_frames-1.1.1/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Coverage artifacts
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Environment and secrets
+.env
+.env.*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Internal-only working docs — kept on disk, never published.
+critiqus/
+perspectives/
+
+# Research lab — code is tracked; generated artifacts are not.
+research/**/.cache/
+research/**/results.tsv
+research/**/run.log
+research/**/audit_plots/

views_frames-1.0.0/README.md → views_frames-1.1.1/PKG-INFO

@@ -1,15 +1,43 @@
+Metadata-Version: 2.4
+Name: views-frames
+Version: 1.1.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
+Project-URL: Changelog, https://github.com/views-platform/views-frames/blob/main/CHANGELOG.md
+Author-email: Simon Polichinel von der Maase <simmaa@prio.org>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy<3,>=1.26
+Provides-Extra: arrow
+Requires-Dist: pyarrow<20,>=14; extra == 'arrow'
+Description-Content-Type: text/markdown
+
 # views-frames
 
 > The VIEWS platform's **data-contract layer**: small, stable, abstract array
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **frozen — v1.0.0** (API freeze, ADR-018). This README is the design
+> **Status:** **v1.1.1 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1.0 surface
+> is purely additive — the coherent posterior summary, ADR-019; v1.1.1 is a docs patch). 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
-> (sample-axis summarization — `collapse`/MAP/HDI/quantiles + cross-level
-> aggregation; ADR-017). The blocking design decisions are resolved (§13a) and
-> ratified as ADRs 011–018; two consumer-review rounds (`perspectives/`) validated
+> (sample-axis summarization — `collapse`/MAP/HDI/quantiles, the coherent-tower estimators
+> `hdi_tower`/`tower_point`/`bimodality`/`summarize_tower`, + cross-level
+> aggregation; ADR-017, ADR-019). The blocking design decisions are resolved (§13a) and
+> ratified as ADRs 011–018; two rounds of consumer review validated
 > the design. Consumer adoption (re-export shims, pandas migration) is the owner's
 > migration, not this repo's.
 > If the code and this README disagree, that is a bug — reconcile before merging.
@@ -67,6 +95,21 @@ Both are numpy-only. For the subtler cm↔pgm surface — a time-varying
 `aggregate_distributions` (`HDI(sum) ≠ sum(HDI)`) — see
 [`examples/cross_level.py`](examples/cross_level.py).
 
+**Which estimator? (two coherent paths, v1.1.0).** Each frozen estimator has a
+coherent-tower sibling (ADR-019): `map_estimate` ↔ `tower_point` (an unbinned
+median-of-the-narrowest-floor point, free of `map_estimate`'s histogram tie-break bias),
+and `hdi`/`quantiles` ↔ `hdi_tower(masses=…)` (HDIs nested **by construction** and
+reproducible — a mass's interval is identical regardless of which others you request),
+with `summarize_tower` returning all three in one pass. Use the **frozen** estimators for
+parity with existing pipelines; use the **tower** path when you need coherent, reproducible
+bands plus a matching point.
+
+**Reading the `bimodality` flag.** It is a *deliberately conservative* heuristic, **not** a
+formal multimodality test — tuned for **zero false positives** at the cost of recall on
+overlapping / unequal mixtures. A `1` means "clearly-separated modes detected"; a `0` means
+**"no clear bimodality detected," not "proven unimodal."** (Full caveat: the `bimodality`
+module docstring; register C-34.)
+
 ---
 
 ## 1. Why this package exists (the problems it kills)
@@ -107,8 +150,7 @@ register):
   first materializes the full-sample tensor). This is C-40/C-66 firing for real —
   pipeline-core **C-186**, the **first observed-in-production member** of the
   Data-Contract Gap cluster, and the live use-case that motivates this package.
-  A dense, collapsed array frame is the fix. See
-  `perspectives/from_views-pipeline-core_perspective.md`.
+  A dense, collapsed array frame is the fix.
 - **God-class data handler with leaked internals.** `_ViewsDataset`
   (`data/handlers.py`, ~950 LOC, C-36) is consumed across three repos by reaching
   into its **private** members (`_time_id`, `_entity_id`, `_get_entity_index`,
@@ -164,14 +206,13 @@ imports **no** `views_*` package, ever. If it ever needs to, the boundary is
 wrong. This is what makes it impossible to participate in a cycle (ADP) and what
 makes it safe to depend on from everywhere (SDP).
 
-> **Consumer perspectives.** A downstream repo's detailed view of how it uses
-> these frames lives in `perspectives/from_<repo>_perspective.md`. The first is
-> `perspectives/from_views-reporting_perspective.md` — the presentation layer that
+> **Consumer views.** Each downstream repo has a detailed view of how it uses
+> these frames. The first is **views-reporting** — the presentation layer that
 > *consumes* `PredictionFrame`, `TargetFrame`, and `MetricFrame` and routes its
 > data contract through this leaf (which is what breaks the
 > views-pipeline-core ↔ views-reporting cycle, reporting issue **#113**).
 >
-> `perspectives/from_views-pipeline-core_perspective.md` is the **origin/orchestration**
+> **views-pipeline-core** is the **origin/orchestration**
 > repo's view — not a pure downstream consumer but the repo that *owns these types
 > today* (`PredictionFrame`, `_ViewsDataset`, the converter) and hands the contract
 > off to this leaf. It carries the worked failure mode (#181 report-stage OOM,
@@ -251,7 +292,7 @@ uses `pd.isna` for the NaN-check (§10.2).
 | **`TargetFrame`** (a.k.a. `ActualsFrame`) | `y_true: (N, 1)` | The **evaluation boundary** still takes pandas actuals (`adapter.py`). A target frame makes eval array-native and kills that pandas dependency. Structurally `PredictionFrame` with `S=1`. | **next** |
 | **`WeightFrame`** | `w: (N,)` or `(N, S)` | Weighted losses / weighted metrics. Same identifiers, different `values` meaning. | when weighting lands |
 | **`MaskFrame`** | `mask: (N,)` bool | Partial-data / sparse-actuals evaluation (C-26 silent truncation). Marks which (time, unit) cells are present. | when partial eval lands |
-| **`MetricFrame`** (a.k.a. `ScoreFrame`) | `(K, …)` keyed by `(target, step, unit)` | Evaluation **outputs** are currently scattered into wandb summaries + parquet. First-class array form. **views-reporting's eval report is the consumer of record** — today it scrapes wandb and renders the wrong run (its C-48; see `perspectives/from_views-reporting_perspective.md`). | exploratory |
+| **`MetricFrame`** (a.k.a. `ScoreFrame`) | `(K, …)` keyed by `(target, step, unit)` | Evaluation **outputs** are currently scattered into wandb summaries + parquet. First-class array form. **views-reporting's eval report is the consumer of record** — today it scrapes wandb and renders the wrong run (its run-selection bug, C-48). | exploratory |
 
 **Already exists externally — do NOT rebuild:** `EvaluationFrame` lives in
 `views-evaluation` (aligned pred×actual×(origin, step)). `views-frames` should
@@ -283,8 +324,8 @@ genuinely reused core. Build this once:
   does not depend on), never fetched or versioned here — embedding versioned domain
   data would make the leaf change for data reasons and break §8 maximal stability.
   This resolves the falsified "domain-free cross-level" claim
-  (`critiqus/critique_02.md`); faoapi's producer-materialised metadata is the
-  existence proof (`perspectives/from_views-faoapi_perspective.md` §8.3).
+  (a falsification audit, 5 hard falsifications); faoapi's producer-materialised
+  metadata is the existence proof.
 - `SpatialLevel` (currently `views-pipeline-core/domain/spatial.py`) should move
   here — it is a tiny, stable value object that *is* part of the identifier
   vocabulary (it defines `index_names` and `entity_column`: cm→`country_id`,
@@ -397,7 +438,7 @@ Layout rules (these *are* the screaming-architecture requirements):
 The scaling failure in the platform today is the **list-in-cell `object`-dtype
 DataFrame** (a cell holds a Python list of S samples) — measured ~33× blow-up
 (C-40/C-66), and ~50–160× per-row over dense float32 in the #181 report-stage
-investigation (C-186; `perspectives/from_views-pipeline-core_perspective.md`).
+investigation (C-186).
 `views-frames` standardizes two scalable formats and **bans list-in-cell**:
 
 - **Native (`io/npz.py`):** `values.npy` (contiguous float32) + `identifiers.npz`.
@@ -511,8 +552,7 @@ typed contract → frame I/O contract), **C-184** (cross-repo mutation of
 (circular dependency) and informs **D-28** (relocate reconciliation) and **D-33**
 (collapse the `CMDataset/PGMDataset` hierarchy into a `SpatialLevel` value).
 
-From the **views-reporting** consumer (its own register; see
-`perspectives/from_views-reporting_perspective.md`) this package *forbids* its
+From the **views-reporting** consumer (its own register) this package *forbids* its
 **C-184** (the `reconciled_dataframe` mutation) and the reporting side of
 **C-135** (private `_entity_id`/`_time_id` reads → published index protocol), and
 *enables* fixing **C-48** (wandb eval scrape → a typed `MetricFrame`) and **C-44**
@@ -549,8 +589,8 @@ pipeline-core **C-48** listed above — two registers, same number.)
    mapping.** Same-level alignment lives in the leaf; the cross-level country↔grid
    join needs a viewser-sourced, time-varying `priogrid→country` **mapping** that
    is **injected by the consumer and never embedded in the leaf**. The leaf owns
-   only `cross_level_align(index, mapping)`. See §4.3; resolves
-   `critiqus/critique_02.md`.
+   only `cross_level_align(index, mapping)`. See §4.3; resolves the
+   falsified "domain-free cross-level" claim (a falsification audit, 5 hard falsifications).
 5. **`SpatialLevel` lives here, as identifier vocabulary only** — relocated with
    the C-65 reversed index-tuple and the `priogrid_gid`/`priogrid_id`
    inconsistency **fixed, not ported** (§4.3). It carries the level labels, never

views_frames-1.0.0/PKG-INFO → views_frames-1.1.1/README.md

@@ -1,31 +1,17 @@
-Metadata-Version: 2.4
-Name: views-frames
-Version: 1.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
-Project-URL: Changelog, https://github.com/views-platform/views-frames/blob/main/CHANGELOG.md
-Author-email: Simon Polichinel von der Maase <simmaa@prio.org>
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: numpy<3,>=1.26
-Provides-Extra: arrow
-Requires-Dist: pyarrow<20,>=14; extra == 'arrow'
-Description-Content-Type: text/markdown
-
 # views-frames
 
 > The VIEWS platform's **data-contract layer**: small, stable, abstract array
 > containers (`FeatureFrame`, `PredictionFrame`, and their anticipated siblings)
 > that every other repo depends on and that depends on nothing internal.
 >
-> **Status:** **frozen — v1.0.0** (API freeze, ADR-018). This README is the design
+> **Status:** **v1.1.1 — frozen API** (frozen since v1.0.0, ADR-018; the v1.1.0 surface
+> is purely additive — the coherent posterior summary, ADR-019; v1.1.1 is a docs patch). 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
-> (sample-axis summarization — `collapse`/MAP/HDI/quantiles + cross-level
-> aggregation; ADR-017). The blocking design decisions are resolved (§13a) and
-> ratified as ADRs 011–018; two consumer-review rounds (`perspectives/`) validated
+> (sample-axis summarization — `collapse`/MAP/HDI/quantiles, the coherent-tower estimators
+> `hdi_tower`/`tower_point`/`bimodality`/`summarize_tower`, + cross-level
+> aggregation; ADR-017, ADR-019). The blocking design decisions are resolved (§13a) and
+> ratified as ADRs 011–018; two rounds of consumer review validated
 > the design. Consumer adoption (re-export shims, pandas migration) is the owner's
 > migration, not this repo's.
 > If the code and this README disagree, that is a bug — reconcile before merging.
@@ -83,6 +69,21 @@ Both are numpy-only. For the subtler cm↔pgm surface — a time-varying
 `aggregate_distributions` (`HDI(sum) ≠ sum(HDI)`) — see
 [`examples/cross_level.py`](examples/cross_level.py).
 
+**Which estimator? (two coherent paths, v1.1.0).** Each frozen estimator has a
+coherent-tower sibling (ADR-019): `map_estimate` ↔ `tower_point` (an unbinned
+median-of-the-narrowest-floor point, free of `map_estimate`'s histogram tie-break bias),
+and `hdi`/`quantiles` ↔ `hdi_tower(masses=…)` (HDIs nested **by construction** and
+reproducible — a mass's interval is identical regardless of which others you request),
+with `summarize_tower` returning all three in one pass. Use the **frozen** estimators for
+parity with existing pipelines; use the **tower** path when you need coherent, reproducible
+bands plus a matching point.
+
+**Reading the `bimodality` flag.** It is a *deliberately conservative* heuristic, **not** a
+formal multimodality test — tuned for **zero false positives** at the cost of recall on
+overlapping / unequal mixtures. A `1` means "clearly-separated modes detected"; a `0` means
+**"no clear bimodality detected," not "proven unimodal."** (Full caveat: the `bimodality`
+module docstring; register C-34.)
+
 ---
 
 ## 1. Why this package exists (the problems it kills)
@@ -123,8 +124,7 @@ register):
   first materializes the full-sample tensor). This is C-40/C-66 firing for real —
   pipeline-core **C-186**, the **first observed-in-production member** of the
   Data-Contract Gap cluster, and the live use-case that motivates this package.
-  A dense, collapsed array frame is the fix. See
-  `perspectives/from_views-pipeline-core_perspective.md`.
+  A dense, collapsed array frame is the fix.
 - **God-class data handler with leaked internals.** `_ViewsDataset`
   (`data/handlers.py`, ~950 LOC, C-36) is consumed across three repos by reaching
   into its **private** members (`_time_id`, `_entity_id`, `_get_entity_index`,
@@ -180,14 +180,13 @@ imports **no** `views_*` package, ever. If it ever needs to, the boundary is
 wrong. This is what makes it impossible to participate in a cycle (ADP) and what
 makes it safe to depend on from everywhere (SDP).
 
-> **Consumer perspectives.** A downstream repo's detailed view of how it uses
-> these frames lives in `perspectives/from_<repo>_perspective.md`. The first is
-> `perspectives/from_views-reporting_perspective.md` — the presentation layer that
+> **Consumer views.** Each downstream repo has a detailed view of how it uses
+> these frames. The first is **views-reporting** — the presentation layer that
 > *consumes* `PredictionFrame`, `TargetFrame`, and `MetricFrame` and routes its
 > data contract through this leaf (which is what breaks the
 > views-pipeline-core ↔ views-reporting cycle, reporting issue **#113**).
 >
-> `perspectives/from_views-pipeline-core_perspective.md` is the **origin/orchestration**
+> **views-pipeline-core** is the **origin/orchestration**
 > repo's view — not a pure downstream consumer but the repo that *owns these types
 > today* (`PredictionFrame`, `_ViewsDataset`, the converter) and hands the contract
 > off to this leaf. It carries the worked failure mode (#181 report-stage OOM,
@@ -267,7 +266,7 @@ uses `pd.isna` for the NaN-check (§10.2).
 | **`TargetFrame`** (a.k.a. `ActualsFrame`) | `y_true: (N, 1)` | The **evaluation boundary** still takes pandas actuals (`adapter.py`). A target frame makes eval array-native and kills that pandas dependency. Structurally `PredictionFrame` with `S=1`. | **next** |
 | **`WeightFrame`** | `w: (N,)` or `(N, S)` | Weighted losses / weighted metrics. Same identifiers, different `values` meaning. | when weighting lands |
 | **`MaskFrame`** | `mask: (N,)` bool | Partial-data / sparse-actuals evaluation (C-26 silent truncation). Marks which (time, unit) cells are present. | when partial eval lands |
-| **`MetricFrame`** (a.k.a. `ScoreFrame`) | `(K, …)` keyed by `(target, step, unit)` | Evaluation **outputs** are currently scattered into wandb summaries + parquet. First-class array form. **views-reporting's eval report is the consumer of record** — today it scrapes wandb and renders the wrong run (its C-48; see `perspectives/from_views-reporting_perspective.md`). | exploratory |
+| **`MetricFrame`** (a.k.a. `ScoreFrame`) | `(K, …)` keyed by `(target, step, unit)` | Evaluation **outputs** are currently scattered into wandb summaries + parquet. First-class array form. **views-reporting's eval report is the consumer of record** — today it scrapes wandb and renders the wrong run (its run-selection bug, C-48). | exploratory |
 
 **Already exists externally — do NOT rebuild:** `EvaluationFrame` lives in
 `views-evaluation` (aligned pred×actual×(origin, step)). `views-frames` should
@@ -299,8 +298,8 @@ genuinely reused core. Build this once:
   does not depend on), never fetched or versioned here — embedding versioned domain
   data would make the leaf change for data reasons and break §8 maximal stability.
   This resolves the falsified "domain-free cross-level" claim
-  (`critiqus/critique_02.md`); faoapi's producer-materialised metadata is the
-  existence proof (`perspectives/from_views-faoapi_perspective.md` §8.3).
+  (a falsification audit, 5 hard falsifications); faoapi's producer-materialised
+  metadata is the existence proof.
 - `SpatialLevel` (currently `views-pipeline-core/domain/spatial.py`) should move
   here — it is a tiny, stable value object that *is* part of the identifier
   vocabulary (it defines `index_names` and `entity_column`: cm→`country_id`,
@@ -413,7 +412,7 @@ Layout rules (these *are* the screaming-architecture requirements):
 The scaling failure in the platform today is the **list-in-cell `object`-dtype
 DataFrame** (a cell holds a Python list of S samples) — measured ~33× blow-up
 (C-40/C-66), and ~50–160× per-row over dense float32 in the #181 report-stage
-investigation (C-186; `perspectives/from_views-pipeline-core_perspective.md`).
+investigation (C-186).
 `views-frames` standardizes two scalable formats and **bans list-in-cell**:
 
 - **Native (`io/npz.py`):** `values.npy` (contiguous float32) + `identifiers.npz`.
@@ -527,8 +526,7 @@ typed contract → frame I/O contract), **C-184** (cross-repo mutation of
 (circular dependency) and informs **D-28** (relocate reconciliation) and **D-33**
 (collapse the `CMDataset/PGMDataset` hierarchy into a `SpatialLevel` value).
 
-From the **views-reporting** consumer (its own register; see
-`perspectives/from_views-reporting_perspective.md`) this package *forbids* its
+From the **views-reporting** consumer (its own register) this package *forbids* its
 **C-184** (the `reconciled_dataframe` mutation) and the reporting side of
 **C-135** (private `_entity_id`/`_time_id` reads → published index protocol), and
 *enables* fixing **C-48** (wandb eval scrape → a typed `MetricFrame`) and **C-44**
@@ -565,8 +563,8 @@ pipeline-core **C-48** listed above — two registers, same number.)
    mapping.** Same-level alignment lives in the leaf; the cross-level country↔grid
    join needs a viewser-sourced, time-varying `priogrid→country` **mapping** that
    is **injected by the consumer and never embedded in the leaf**. The leaf owns
-   only `cross_level_align(index, mapping)`. See §4.3; resolves
-   `critiqus/critique_02.md`.
+   only `cross_level_align(index, mapping)`. See §4.3; resolves the
+   falsified "domain-free cross-level" claim (a falsification audit, 5 hard falsifications).
 5. **`SpatialLevel` lives here, as identifier vocabulary only** — relocated with
    the C-65 reversed index-tuple and the `priogrid_gid`/`priogrid_id`
    inconsistency **fixed, not ported** (§4.3). It carries the level labels, never

{views_frames-1.0.0 → views_frames-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "views-frames"
-version = "1.0.0"
+version = "1.1.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" },
@@ -13,6 +13,20 @@ readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 license-files = ["LICENSE"]
+# License is declared via the SPDX `license` expression above (PEP 639); the deprecated
+# `License ::` classifier is intentionally omitted to avoid the expression/classifier clash.
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
 dependencies = [
     "numpy>=1.26,<3",
 ]
@@ -29,6 +43,7 @@ arrow = ["pyarrow>=14,<20"]
 [dependency-groups]
 dev = [
     "pytest>=8.0",
+    "pytest-cov>=5",
     "ruff>=0.8",
     "mypy>=1.13",
     # pyarrow is the consumer-facing [arrow] extra; installed in dev so CI
@@ -46,9 +61,24 @@ include = ["/src"]
 testpaths = ["tests"]
 addopts = "-ra -q"
 
+# Coverage: the leaf is critical infrastructure (ADR-005) — CI enforces 100%
+# line coverage (`uv run pytest --cov --cov-fail-under=100`). Genuinely
+# unreachable defensive lines must carry an explicit `# pragma: no cover`.
+[tool.coverage.run]
+source = ["src"]
+# Branch coverage on: the `--cov-fail-under=100` gate enforces line AND branch
+# coverage, so a conditional with an untested outcome fails CI (register C-36).
+branch = true
+
+[tool.coverage.report]
+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"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "UP", "B", "A", "C4", "SIM"]

{views_frames-1.0.0 → views_frames-1.1.1}/src/views_frames_summarize/__init__.py

@@ -15,15 +15,24 @@ from views_frames_summarize.aggregate import (
     aggregate_distributions,
     aggregate_distributions_arrays,
 )
+from views_frames_summarize.bimodality import bimodality
 from views_frames_summarize.collapse import collapse
 from views_frames_summarize.interval import hdi, quantiles
 from views_frames_summarize.point import map_estimate
+from views_frames_summarize.summarize_tower import TowerSummary, summarize_tower
+from views_frames_summarize.tower import hdi_tower
+from views_frames_summarize.tower_point import tower_point
 
 __all__ = [
+    "TowerSummary",
     "aggregate_distributions",
     "aggregate_distributions_arrays",
+    "bimodality",
     "collapse",
     "hdi",
+    "hdi_tower",
     "map_estimate",
     "quantiles",
+    "summarize_tower",
+    "tower_point",
 ]

views_frames-1.1.1/src/views_frames_summarize/bimodality.py

@@ -0,0 +1,113 @@
+"""Per-row bimodality flag (ADR-019) — a `(N, …, 1)` array aligned to the index.
+
+A genuinely two-peaked posterior — a zero atom plus a *distinct* positive bump, or two
+well-separated positive bumps — has no well-defined "most likely single value" and no
+well-defined shortest interval (the shortest 50% interval flips between the peaks under
+tiny perturbations, at *any* grid density). `bimodality` flags those rows so a consumer
+is never handed a single point / interval that silently hides a second mode.
+
+The detector is a **deliberately conservative heuristic**, not a formal multimodality
+test. Per row: a coarse, lightly-smoothed histogram; then a count of *separated*
+density regions — runs of bins at least ``prominence`` of the row's peak, with
+sub-``prominence`` valleys between them — keeping only regions that carry at least
+``min_mass`` of the samples. A row is flagged iff ≥ 2 such regions survive. Quiet rows
+(the zero short-circuit) are never flagged.
+
+It is tuned (against the research battery) for **zero false positives** on the normal
+regime — right-skewed, zero-inflated and active unimodal posteriors all read as
+unimodal — at the cost of recall on *ambiguous*, overlapping mixtures. That trade is
+intentional: today's models are effectively unimodal, so the flag's job is to catch a
+future regime change that produces *clearly* separated modes, not to adjudicate every
+heavy tail. A missed subtle bump is cheaper than crying wolf on every skewed cell.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames_summarize._common import ROW_BLOCK, AnyFrame, block_apply
+from views_frames_summarize.tower import _zero_mask
+
+_SMOOTH = 3  # moving-average window over bins; tames sparse-histogram flicker
+
+
+def _coarse_counts(flat: NDArray[np.float32], bins: int) -> NDArray[np.intp]:
+    """Per-row histogram counts ``(rows, bins)`` over each row's ``[min, max]``.
+
+    A simple clipped linear bucket (not ``numpy.histogram``'s edge-exact path) —
+    enough to locate density regions. All-equal rows fall into a single bin.
+    """
+    rows = flat.shape[0]
+    first = flat.min(axis=1)
+    last = flat.max(axis=1)
+    span = np.where(first == last, np.float32(1.0), last - first)
+    idx = (((flat - first[:, None]) / span[:, None]) * bins).astype(np.intp)
+    np.clip(idx, 0, bins - 1, out=idx)
+    offsets = idx + (np.arange(rows)[:, None] * bins)
+    return np.bincount(offsets.ravel(), minlength=rows * bins).reshape(rows, bins)
+
+
+def _bimodal_block(
+    block: NDArray[np.float32], bins: int, prominence: float, min_mass: float
+) -> NDArray[np.float32]:
+    """Flag (0/1) per row of a block: ≥ 2 separated regions each holding enough mass."""
+    rows = block.shape[0]
+    counts = _coarse_counts(block, bins).astype(np.float64)
+
+    # Light moving-average smoothing (window _SMOOTH) over the bins. Normalise each
+    # position by the number of *real* bins in its window — the two edge bins have one
+    # fewer neighbour, so dividing them by the full window would deflate an edge peak
+    # (e.g. the zero atom, which always lands in bin 0) and hide an atom+bump bimodal.
+    pad = np.zeros((rows, 1))
+    padded = np.concatenate([pad, counts, pad], axis=1)
+    window_sum = padded[:, :-2] + padded[:, 1:-1] + padded[:, 2:]
+    divisor = np.full(bins, _SMOOTH, dtype=np.float64)
+    divisor[0] = divisor[-1] = _SMOOTH - 1  # edges contribute one fewer real bin
+    smooth = window_sum / divisor
+
+    significant = smooth >= prominence * smooth.max(axis=1, keepdims=True)
+    prev = np.concatenate(
+        [np.zeros((rows, 1), dtype=bool), significant[:, :-1]], axis=1
+    )
+    starts = significant & ~prev
+    # Label each maximal run of significant bins with a per-row region index (1-based).
+    region = np.where(significant, np.cumsum(starts, axis=1), 0)
+
+    total = counts.sum(axis=1)
+    kept = np.zeros(rows, dtype=np.intp)
+    for r in range(
+        1, int(region.max()) + 1
+    ):  # <= bins iterations, vectorized over rows
+        mass = np.where(region == r, counts, 0.0).sum(axis=1)
+        kept += (mass >= min_mass * total).astype(np.intp)
+
+    flag = (kept >= 2).astype(np.float32)
+    flag[_zero_mask(block)] = 0.0
+    return flag
+
+
+def bimodality(
+    frame: AnyFrame,
+    *,
+    bins: int = 16,
+    prominence: float = 0.40,
+    min_mass: float = 0.15,
+    block_rows: int = ROW_BLOCK,
+) -> NDArray[np.float32]:
+    """Per-row bimodality flag over the sample axis → ``(N, …, 1)`` of ``0.0``/``1.0``.
+
+    Conservative heuristic (see module docstring): ≥ 2 separated density regions, each
+    holding ≥ ``min_mass`` of the samples, after coarse binning + light smoothing.
+    Aligned to ``frame.index``.
+    """
+    values = frame.values
+    lead = values.shape[:-1]
+    s = values.shape[-1]
+    flat = np.ascontiguousarray(values).reshape(-1, s)
+
+    def _block(block: NDArray[np.float32]) -> NDArray[np.float32]:
+        return _bimodal_block(block, bins, prominence, min_mass)
+
+    out = block_apply(flat, block_rows, _block)
+    return np.asarray(out, dtype=np.float32).reshape(lead)[..., np.newaxis]

views_frames-1.1.1/src/views_frames_summarize/conformance.py

@@ -0,0 +1,87 @@
+"""Conformance checks for the summarize package (ADR-016/017).
+
+A consumer can re-run these against its own frame factories to confirm the
+summarizers behave: point estimates return same-type `(N, …, 1)` frames; interval
+estimates return arrays aligned to the input frame's rows.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from views_frames_summarize._common import AnyFrame
+from views_frames_summarize.bimodality import bimodality
+from views_frames_summarize.collapse import collapse
+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_point import tower_point
+
+
+def assert_summarizer_contract(frame: AnyFrame) -> None:
+    """Assert the summarizers behave on ``frame``.
+
+    Raises:
+        AssertionError: a summarizer violates its output contract.
+    """
+    n = frame.n_rows
+
+    point = collapse(frame, np.mean)
+    assert type(point) is type(frame), "collapse must return the same frame type"
+    assert point.values.shape[-1] == 1, "collapse must reduce the sample axis to 1"
+    assert point.n_rows == n, "collapse must preserve rows"
+
+    mode = map_estimate(frame)
+    assert mode.values.shape[-1] == 1 and mode.n_rows == n, "map_estimate → (N,…,1)"
+
+    lo_hi = hdi(frame, mass=0.9)
+    assert lo_hi.shape[0] == n, "hdi must be aligned to the frame's rows"
+    assert lo_hi.shape[-1] == 2, "hdi must produce (lower, upper)"
+
+    qs = quantiles(frame, [0.1, 0.5, 0.9])
+    assert qs.shape[0] == n, "quantiles must be aligned to the frame's rows"
+    assert qs.shape[-1] == 3, "quantiles must produce one column per quantile"
+
+    _assert_tower_contract(frame, n)
+
+
+def _assert_tower_contract(frame: AnyFrame, n: int) -> None:
+    """Assert the constrained-nested tower's contract + its laws (ADR-019)."""
+    tip = tower_point(frame)
+    assert type(tip) is type(frame), "tower_point must return the same frame type"
+    assert tip.values.shape[-1] == 1 and tip.n_rows == n, "tower_point → (N,…,1)"
+
+    flag = bimodality(frame)
+    assert flag.shape[0] == n and flag.shape[-1] == 1, "bimodality → (N,…,1)"
+    assert np.isin(flag, (0.0, 1.0)).all(), "bimodality must be a 0/1 flag"
+
+    tower = hdi_tower(frame, masses=(0.5, 0.9, 0.99))
+    assert tower.shape[0] == n, "hdi_tower must be aligned to the frame's rows"
+    assert tower.shape[-2:] == (3, 2), "hdi_tower → (…, M, 2)"
+
+    # Nesting law: every wider HDI contains the next-narrower one.
+    lower, upper = tower[..., 0], tower[..., 1]
+    assert (np.diff(lower, axis=-1) <= 1e-6).all(), (
+        "tower lowers must be non-increasing"
+    )
+    assert (np.diff(upper, axis=-1) >= -1e-6).all(), (
+        "tower uppers must be non-decreasing"
+    )
+
+    # Tip-in-narrowest law: the point lies inside the narrowest requested floor.
+    lo0, hi0 = tower[..., 0, 0], tower[..., 0, 1]
+    assert (tip.values[..., 0] >= lo0 - 1e-6).all(), "tip below the narrowest floor"
+    assert (tip.values[..., 0] <= hi0 + 1e-6).all(), "tip above the narrowest floor"
+
+    # Reproducibility law: the 50% HDI is independent of the other requested masses.
+    just_50 = hdi_tower(frame, masses=(0.5,))
+    assert np.array_equal(just_50[..., 0, :], tower[..., 0, :]), (
+        "the 50% HDI must be identical whether or not other masses are requested"
+    )
+
+    # The bundle is exactly the three composable functions.
+    bundle = summarize_tower(frame, masses=(0.5, 0.9, 0.99))
+    assert np.array_equal(bundle.point.values, tip.values), "bundle point ≠ tower_point"
+    assert np.array_equal(bundle.intervals, tower), "bundle intervals ≠ hdi_tower"
+    assert np.array_equal(bundle.bimodal, flag), "bundle bimodal ≠ bimodality"

{views_frames-1.0.0 → views_frames-1.1.1}/src/views_frames_summarize/point.py

@@ -35,6 +35,13 @@ def map_estimate(
     For each row: if a fraction ``>= zero_mass_threshold`` of the samples is ~0 the
     MAP is ``0.0``; otherwise it is the centre of the densest histogram bin. The
     work runs in row-blocks of ``block_rows`` to bound peak memory (register C-22).
+
+    Caveat (register C-32): the densest-bin tie-break is the **lowest bin index**
+    (deterministic; register C-24). At low sample counts the histogram peak is
+    usually a multi-way tie, and lowest-index = leftmost = smallest value — so for
+    **right-skewed, zero-inflated** posteriors the mode is biased toward the left
+    tail (zero). This is therefore **not a drop-in** for a production histogram-MAP
+    on such distributions; a robust mode estimator is tracked separately (#89).
     """
     values = frame.values
     lead = values.shape[:-1]
@@ -97,6 +104,9 @@ def _batched_map(flat: NDArray[np.float32], bins: int) -> NDArray[np.float32]:
     # the float64 bin widths differ by ~1 ulp across numpy versions and flip the
     # argmax (register C-24). Integer ``argmax`` is deterministic and identical on
     # every numpy build, so ``map_estimate`` is portable and reproducible.
+    # NOTE (register C-32): lowest-index == leftmost == smallest value, so on the
+    # frequent low-sample ties this biases the mode toward zero for right-skewed,
+    # zero-inflated posteriors. Portable but not unbiased; redesign tracked in #89.
     densest = np.argmax(counts, axis=1)
 
     lo = np.take_along_axis(edges, densest[:, None], axis=1)[:, 0]

views_frames-1.1.1/src/views_frames_summarize/summarize_tower.py

@@ -0,0 +1,89 @@
+"""The single-pass coherent posterior summary (ADR-019).
+
+`summarize_tower` is the dashboard hot path: it sorts each row-block **once** and builds
+the canonical tower **once**, deriving the tower-tip point, the pinned nested HDIs, and
+the bimodality flag together. It returns exactly what the three composable functions
+(`tower_point`, `hdi_tower`, `bimodality`) return — the bundle is purely an efficiency
+collapse of the three, not a different computation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import NamedTuple
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames_summarize._common import ROW_BLOCK, AnyFrame, rebuild
+from views_frames_summarize.bimodality import _bimodal_block
+from views_frames_summarize.tower import (
+    _CANONICAL_FLOORS,
+    _dense_tower,
+    _ks,
+    _pin,
+    _tip,
+    _zero_mask,
+)
+
+
+class TowerSummary(NamedTuple):
+    """The coherent summary of a frame's posteriors over the sample axis.
+
+    Attributes:
+        point: ``(N, …, 1)`` frame — the tower-tip point estimate.
+        intervals: ``(N, …, M, 2)`` array — nested HDIs at the pinned masses.
+        bimodal: ``(N, …, 1)`` array — the per-row bimodality flag (0/1).
+        masses: ``(M,)`` array — the canonical floors the requested masses pinned to.
+    """
+
+    point: AnyFrame
+    intervals: NDArray[np.float32]
+    bimodal: NDArray[np.float32]
+    masses: NDArray[np.float32]
+
+
+def summarize_tower(
+    frame: AnyFrame,
+    masses: Sequence[float] = (0.5, 0.9, 0.99),
+    *,
+    bins: int = 16,
+    prominence: float = 0.40,
+    min_mass: float = 0.15,
+    block_rows: int = ROW_BLOCK,
+) -> TowerSummary:
+    """Point + nested HDIs + bimodality flag in one sort-once pass → `TowerSummary`."""
+    values = frame.values
+    lead = values.shape[:-1]
+    s = values.shape[-1]
+    ks = _ks(s)
+    pin = _pin(masses)
+    k0 = int(ks[0])
+    flat = np.ascontiguousarray(values).reshape(-1, s)
+    rows = flat.shape[0]
+
+    point_flat = np.empty(rows, dtype=np.float32)
+    intervals_flat = np.empty((rows, pin.shape[0], 2), dtype=np.float32)
+    bimodal_flat = np.empty(rows, dtype=np.float32)
+
+    for start in range(0, rows, block_rows):
+        block = flat[start : start + block_rows]
+        srt = np.sort(block, axis=-1)
+        zero = _zero_mask(block)
+
+        sel = _dense_tower(srt, ks)[:, pin, :]
+        sel[zero] = 0.0
+        tip = np.where(zero, np.float32(0.0), _tip(srt, k0))
+
+        stop = start + block.shape[0]
+        point_flat[start:stop] = tip
+        intervals_flat[start:stop] = sel
+        bimodal_flat[start:stop] = _bimodal_block(block, bins, prominence, min_mass)
+
+    point = rebuild(frame, point_flat.reshape(lead)[..., np.newaxis])
+    intervals = intervals_flat.reshape(*lead, pin.shape[0], 2)
+    bimodal = bimodal_flat.reshape(lead)[..., np.newaxis]
+    pinned = _CANONICAL_FLOORS[pin].astype(np.float32)
+    return TowerSummary(
+        point=point, intervals=intervals, bimodal=bimodal, masses=pinned
+    )

views_frames-1.1.1/src/views_frames_summarize/tower.py

@@ -0,0 +1,192 @@
+"""The constrained-nested HDI tower (ADR-019) — interval estimates over the sample axis.
+
+`hdi_tower` returns, for each requested mass, the highest-density interval read out
+of a **fixed canonical tower**: a dense set of shortest intervals built inside-out so
+each floor is the shortest interval that *contains* the next-narrower one. Nesting is
+therefore guaranteed **by construction** (no post-hoc "move to nest" patch; register
+C-33), and because the tower is always built on the same fixed `_CANONICAL_FLOORS`
+grid — with requested masses *pinned* to the nearest floor, never inserted — "the 50%
+HDI" is identical regardless of which other masses a caller asks for (reproducibility).
+
+The construction is vectorized over the sample axis and runs in row-blocks (register
+C-22/C-25): one sort per block, never a whole-grid sorted copy. A raw-count zero
+short-circuit (`max(row) <= 1.0` → the whole summary collapses to 0) kills the quiet
+cells — the overwhelming majority — cheaply.
+
+Returns numpy arrays aligned to the frame's index (the interval convention, ADR-017);
+the caller holds the index. The private engine here (`_dense_tower`, `_tip`, `_pin`,
+`_zero_mask`, `_CANONICAL_FLOORS`) is shared by `tower_point`, `bimodality`, and the
+single-pass `summarize_tower` bundle.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Final
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames_summarize._common import ROW_BLOCK, AnyFrame, block_apply
+
+# The fixed canonical mass grid: a 5% body plus a fixed fine high-mass tail so a
+# requested 0.99 pins to 0.99 (not 0.95). Built from rounded literals — NOT
+# ``np.arange`` (whose float accumulation drifts ~1 ulp across numpy versions and
+# would make the grid, and therefore every pinned interval, non-reproducible).
+_CANONICAL_FLOORS: Final[NDArray[np.float64]] = np.array(
+    [round(0.05 * i, 2) for i in range(1, 19)]  # 0.05 … 0.90
+    + [0.92, 0.94, 0.95, 0.96, 0.97, 0.98, 0.99],  # fine high-mass tail (incl. 0.95)
+    dtype=np.float64,
+)
+
+# Raw-count zero rule: a row whose every draw is <= this collapses to 0 (the quiet
+# cell — no meaningful positive mass). Deliberately a *count* rule, distinct from
+# ``map_estimate``'s zero-*mass*-fraction rule, so the two estimators stay independent.
+_ZERO_CUTOFF: Final = 1.0
+
+
+def _ks(sample_count: int) -> NDArray[np.intp]:
+    """The per-floor window size ``k = floor(mass * S)`` for every canonical floor."""
+    return np.asarray(np.floor(_CANONICAL_FLOORS * sample_count), dtype=np.intp)
+
+
+def _pin(masses: Sequence[float]) -> NDArray[np.intp]:
+    """Index of the nearest canonical floor for each requested mass.
+
+    Deterministic: ``argmin`` of the distance, breaking ties on the lowest index. A
+    mass at the midpoint between two floors (e.g. ``0.075`` between ``0.05`` and
+    ``0.10``) therefore pins **down** to the lower floor — unambiguous and
+    reproducible. Fails loud (ADR-008) on a mass outside ``(0, 1)`` rather than silently
+    pinning a nonsense value to the nearest floor and returning a plausible interval.
+    """
+    m = np.asarray(masses, dtype=np.float64)
+    if m.size == 0 or not np.all((m > 0.0) & (m < 1.0)):
+        raise ValueError(
+            f"masses must each be in the open interval (0, 1); got {masses!r}"
+        )
+    dist = np.abs(_CANONICAL_FLOORS[None, :] - m[:, None])
+    return np.asarray(np.argmin(dist, axis=1), dtype=np.intp)
+
+
+def _zero_mask(block: NDArray[np.float32]) -> NDArray[np.bool_]:
+    """Rows whose maximum draw is at/below the zero cutoff — the quiet cells."""
+    return np.asarray(block.max(axis=-1) <= _ZERO_CUTOFF, dtype=np.bool_)
+
+
+def _shortest(
+    srt: NDArray[np.float32], k: int
+) -> tuple[NDArray[np.float32], NDArray[np.float32]]:
+    """Shortest interval holding ``k + 1`` samples, per row of a sorted block.
+
+    For ``k <= 0`` the floor cannot hold two samples (``S`` below the grid's 1/S
+    resolution); it degenerates to the per-row median point — the tower-tip seed.
+    """
+    n = srt.shape[-1]
+    if k <= 0:
+        v = srt[:, n // 2]
+        return v.copy(), v.copy()
+    widths = srt[:, k:] - srt[:, : n - k]
+    i = np.argmin(widths, axis=-1)
+    lo = np.take_along_axis(srt, i[:, None], axis=-1)[:, 0]
+    hi = np.take_along_axis(srt, (i + k)[:, None], axis=-1)[:, 0]
+    return lo, hi
+
+
+def _shortest_containing(
+    srt: NDArray[np.float32],
+    k: int,
+    plo: NDArray[np.float32],
+    phi: NDArray[np.float32],
+) -> tuple[NDArray[np.float32], NDArray[np.float32]]:
+    """Shortest ``k+1``-sample interval that contains the inner floor ``[plo, phi]``.
+
+    This is what makes the tower nested by construction. ``k <= 0`` inherits the inner
+    floor; ``k >= n-1`` is the whole row.
+    """
+    n = srt.shape[-1]
+    if k <= 0:
+        return plo.copy(), phi.copy()
+    if k >= n - 1:
+        return srt[:, 0].copy(), srt[:, -1].copy()
+    starts = srt[:, : n - k]
+    ends = srt[:, k:]
+    ok = (starts <= plo[:, None]) & (ends >= phi[:, None])
+    widths = np.where(ok, ends - starts, np.inf)
+    i = np.argmin(widths, axis=-1)
+    lo = np.take_along_axis(starts, i[:, None], axis=-1)[:, 0]
+    hi = np.take_along_axis(ends, i[:, None], axis=-1)[:, 0]
+    # Defensive: the construction guarantees an inner floor is itself a sample window,
+    # so a wider containing window always exists — but if that invariant is ever
+    # broken, expand minimally rather than emit a non-nested floor.
+    bad = ~np.isfinite(widths.min(axis=-1))
+    if bad.any():  # pragma: no cover - unreachable while inner ⊂ outer holds
+        lo = np.where(bad, np.minimum(srt[:, 0], plo), lo)
+        hi = np.where(bad, np.maximum(srt[:, -1], phi), hi)
+    return lo, hi
+
+
+def _dense_tower(srt: NDArray[np.float32], ks: NDArray[np.intp]) -> NDArray[np.float32]:
+    """Build the full constrained-nested tower over a sorted block → ``(rows, F, 2)``.
+
+    F is the number of canonical floors; each is nested in the next-wider one.
+    """
+    rows = srt.shape[0]
+    out = np.empty((rows, ks.shape[0], 2), dtype=np.float32)
+    plo: NDArray[np.float32] | None = None
+    phi: NDArray[np.float32] | None = None
+    for j, k in enumerate(ks):
+        if plo is None or phi is None:
+            lo, hi = _shortest(srt, int(k))
+        else:
+            lo, hi = _shortest_containing(srt, int(k), plo, phi)
+        out[:, j, 0] = lo
+        out[:, j, 1] = hi
+        plo, phi = lo, hi
+    return out
+
+
+def _tip(srt: NDArray[np.float32], k0: int) -> NDArray[np.float32]:
+    """The tower tip: the median of the narrowest floor's ``k0 + 1`` samples, per row.
+
+    For ``k0 <= 0`` the floor is the median point itself.
+    """
+    n = srt.shape[-1]
+    if k0 <= 0:
+        return np.array(srt[:, n // 2], dtype=np.float32)
+    widths = srt[:, k0:] - srt[:, : n - k0]
+    i = np.argmin(widths, axis=-1)
+    lo_mid = i + (k0 // 2)
+    hi_mid = i + ((k0 + 1) // 2)
+    a = np.take_along_axis(srt, lo_mid[:, None], axis=-1)[:, 0]
+    b = np.take_along_axis(srt, hi_mid[:, None], axis=-1)[:, 0]
+    return np.asarray((a + b) * 0.5, dtype=np.float32)
+
+
+def hdi_tower(
+    frame: AnyFrame,
+    masses: Sequence[float] = (0.5, 0.9, 0.99),
+    *,
+    block_rows: int = ROW_BLOCK,
+) -> NDArray[np.float32]:
+    """Per-row constrained-nested HDIs at the requested ``masses`` → ``(N, …, M, 2)``.
+
+    Each requested mass is pinned to the nearest fixed canonical floor; the interval is
+    read out of the full canonical tower (built once per block). Nested by construction
+    and reproducible (a mass's interval is independent of the other requested masses).
+    Quiet rows (``max <= 1``) collapse to ``(0, 0)``. Aligned to ``frame.index``.
+    """
+    values = frame.values
+    lead = values.shape[:-1]
+    s = values.shape[-1]
+    ks = _ks(s)
+    pin = _pin(masses)
+    flat = np.ascontiguousarray(values).reshape(-1, s)
+
+    def _block(block: NDArray[np.float32]) -> NDArray[np.float32]:
+        srt = np.sort(block, axis=-1)
+        sel = _dense_tower(srt, ks)[:, pin, :]
+        sel[_zero_mask(block)] = 0.0
+        return sel
+
+    out = block_apply(flat, block_rows, _block)
+    return np.asarray(out, dtype=np.float32).reshape(*lead, pin.shape[0], 2)

views_frames-1.1.1/src/views_frames_summarize/tower_point.py

@@ -0,0 +1,46 @@
+"""The tower-tip point estimate (ADR-019) — a `(N, …, 1)` frame.
+
+`tower_point` is the "most likely single value" we report to a consumer: the median of
+the draws inside the **narrowest canonical floor** of the constrained-nested tower (the
+tip), with the same raw-count zero short-circuit as the tower (`max(row) <= 1` → 0).
+
+It is a *new* estimator, deliberately distinct from the frozen `map_estimate` (ADR-018):
+`map_estimate` is a binned histogram mode with a zero-*mass*-fraction rule and a
+lowest-index tie-break that is directionally biased on right-skewed, zero-inflated,
+low-sample posteriors (register C-32). The tower tip is unbinned — it reads the median
+of an actual shortest-interval window — so it carries no histogram tie-break. On a
+genuinely multi-peaked row the tip is, like any single point, ambiguous; pair it with
+`bimodality` to detect that case rather than collapse it silently.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from views_frames_summarize._common import ROW_BLOCK, AnyFrame, block_apply, rebuild
+from views_frames_summarize.tower import _CANONICAL_FLOORS, _tip, _zero_mask
+
+
+def tower_point(frame: AnyFrame, *, block_rows: int = ROW_BLOCK) -> AnyFrame:
+    """Per-row tower-tip point estimate over the sample axis → a `(N, …, 1)` frame.
+
+    The median of the narrowest canonical floor's samples; ``0.0`` for quiet rows
+    (every draw ``<= 1``). Returns a frame of the same type as ``frame``.
+    """
+    values = frame.values
+    lead = values.shape[:-1]
+    s = values.shape[-1]
+    k0 = int(np.floor(_CANONICAL_FLOORS[0] * s))
+    flat = np.ascontiguousarray(values).reshape(-1, s)
+
+    def _block(block: NDArray[np.float32]) -> NDArray[np.float32]:
+        srt = np.sort(block, axis=-1)
+        tip = _tip(srt, k0)
+        return np.asarray(
+            np.where(_zero_mask(block), np.float32(0.0), tip), dtype=np.float32
+        )
+
+    out = block_apply(flat, block_rows, _block)
+    reduced = np.asarray(out, dtype=np.float32).reshape(lead)[..., np.newaxis]
+    return rebuild(frame, reduced)

views_frames-1.0.0/.gitignore

@@ -1,30 +0,0 @@
-# Python
-__pycache__/
-*.py[cod]
-*.egg-info/
-dist/
-build/
-.eggs/
-
-# Virtual environments
-.venv/
-venv/
-
-# Tool caches
-.pytest_cache/
-.ruff_cache/
-.mypy_cache/
-
-# Environment and secrets
-.env
-.env.*
-
-# OS
-.DS_Store
-Thumbs.db
-
-# IDE
-.idea/
-.vscode/
-*.swp
-*.swo

views_frames-1.0.0/src/views_frames_summarize/conformance.py

@@ -1,40 +0,0 @@
-"""Conformance checks for the summarize package (ADR-016/017).
-
-A consumer can re-run these against its own frame factories to confirm the
-summarizers behave: point estimates return same-type `(N, …, 1)` frames; interval
-estimates return arrays aligned to the input frame's rows.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from views_frames_summarize._common import AnyFrame
-from views_frames_summarize.collapse import collapse
-from views_frames_summarize.interval import hdi, quantiles
-from views_frames_summarize.point import map_estimate
-
-
-def assert_summarizer_contract(frame: AnyFrame) -> None:
-    """Assert the summarizers behave on ``frame``.
-
-    Raises:
-        AssertionError: a summarizer violates its output contract.
-    """
-    n = frame.n_rows
-
-    point = collapse(frame, np.mean)
-    assert type(point) is type(frame), "collapse must return the same frame type"
-    assert point.values.shape[-1] == 1, "collapse must reduce the sample axis to 1"
-    assert point.n_rows == n, "collapse must preserve rows"
-
-    mode = map_estimate(frame)
-    assert mode.values.shape[-1] == 1 and mode.n_rows == n, "map_estimate → (N,…,1)"
-
-    lo_hi = hdi(frame, mass=0.9)
-    assert lo_hi.shape[0] == n, "hdi must be aligned to the frame's rows"
-    assert lo_hi.shape[-1] == 2, "hdi must produce (lower, upper)"
-
-    qs = quantiles(frame, [0.1, 0.5, 0.9])
-    assert qs.shape[0] == n, "quantiles must be aligned to the frame's rows"
-    assert qs.shape[-1] == 3, "quantiles must produce one column per quantile"