Skip to content

ADR-027 — Convenience surface and the MinMaxSummary rename

  • Identifier: ADR-027
  • Title: Convenience surface (zero-cost helpers, range/span overloads) and the MinMaxSummary rename
  • Status: Accepted
  • Source: authored at 0.8 from the external API-ergonomics review; amends the public API inventory in docs/prd/04-public-api.md §3.6 per the PRD amendment process. This file is the canonical, living ADR record.
  • ADR-027 — Convenience surface and the MinMaxSummary rename. Status: Accepted. Context: an external ergonomics review found the buffer-oriented core sound but clerical for ordinary C++ callers: BitmapView{nullptr} noise, hand-written (n + 7) / 8, repeated data()/size() view spelling, and result counts detached from results. It also found one actively misleading name: Sma<T>/compute_sma reads as "simple moving average" but computes the fused min/max/null-count summary. Problem: improve call-site ergonomics without compromising the core's properties (no allocation, explicit storage, runtime dispatch, exact semantics) and fix the misleading name before v1.0 freezes it. Alternatives: (1) fluent/expression-template DSL (column(v).where(...).sum()) — rejected: requires ownership policy, laziness rules, error propagation, and grows toward the engine the Charter prohibits (T1); (2) an owning quiver::stl layer returning std::vector — deferred until external feedback shows demand (allocating helpers are undesirable inside real analytical loops); (3) keep Sma because the API was declared frozen — rejected: a frozen mistake remains a mistake, and 0.x explicitly permits breaking changes with a minor bump (REQ-REL-001, Charter §7.5); (4) thin zero-cost convenience layer over the unchanged primitives (selected): all_valid (the named BitmapView{nullptr}), bitmap_bytes(n), batch_view(range)/selection_view(range) builders, validity-parameter defaults and no-validity overloads, range-in/span-out kernel overloads that assert output capacity (assertion builds) and return the written subspan so results carry their counts, CheckedSum<T>+sum_checked replacing the pointer-out-parameter pattern, and the rename Sma → MinMaxSummary, compute_sma → compute_min_max with [[deprecated]] aliases kept through 0.x and removed at v1.0. Consequences: every convenience form forwards to an existing primitive — no new kernel entry points, no allocation, no behavior change, differential/property suites unchanged in meaning; internal kernel symbols (k6_compute_sma) keep their historical token to avoid dispatch-table churn; the public headers gain <span>/<ranges> includes. Reconsideration: the owning quiver::stl layer (alternative 2) if downstream feedback asks for it. Related: REQ-API-009, REQ-REL-001, API-K6-004, Charter T1/T6.