columna-core 0.7.8__tar.gz

columna_core-0.7.8/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+*.swp
+
+# Raw handoff bundle (provenance, not part of the deliverable)
+attachments/

columna_core-0.7.8/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to **columna-core** are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses the `-core` version line
+carried in `columna_core.__version__`.
+
+The entries below are extracted from the README version-history blocks (the de-facto changelog to
+date); future changes are recorded here going forward.
+
+## [0.7.8-core] — packaging hardening + the disclosure wire adapter
+
+**Packaging / correctness (crediting the WP-0 acceptance audit):**
+- Declare the hard `pyarrow>=15` runtime dependency. `connector.py` calls
+  `pl.from_arrow(con.execute(q).arrow())` on every fetch and polars does not pull pyarrow
+  transitively, so a clean-venv install imported fine but failed on first fetch. A wheel smoke test
+  (fresh venv → real fetch) now guards this in CI.
+- Resolve `COLUMNA_BENCH_WAREHOUSE` to an absolute path at read time, so a relative value no longer
+  silently mis-resolves against the demo runner's cwd.
+- Reconcile `benchmark.cml` with the code-built Manifold by adding the `region_label` measure
+  (parser now yields 6 measures == the code set; `parse_benchmark` exits 0 on parity YES). A
+  structural parity test guards against re-drift.
+
+**v0.7.8 worklist (items 1–2), cleared:**
+- `parser.py`: import `Optional` (fixes F821 — annotation-only, was masked by
+  `from __future__ import annotations`; would have broken `typing.get_type_hints(parse_predicate)`).
+- Remove unused imports / dead locals / a placeholder-less f-string across `disclosure.py`,
+  `engine.py`, `model.py`, `parser.py`; the corresponding per-file-ignores are tightened back out.
+
+**New:**
+- `columna_core.disclosure_wire` — the structured `{code, materiality, …}` wire adapter (the
+  category → (code, default materiality) table is normative, one dict). This is the ADR-032 D8 "one
+  contract" serialization the MCP surface (WP-2.2) and every other surface share; WP-1.3 collapses
+  into it.
+
+## [0.7.7-core] — ON UNIVERSE pin wiring (Option A)
+The population pin recorded by `Frame.on_universe(u)` is threaded to the planner (`run`/`plan` →
+`_infer`) where it asserts the frame's intended population: a measure bound to `u` serves; a measure
+bound to a *different* universe is out-of-domain and **refuses** (`out_of_universe`); an unknown `u`
+is an **error**. Resolves the multi-universe / D5 co-anchoring ambiguity to the one chosen
+population. 124 checks across 11 suites.
+
+## [0.7.6-core] — the no-result is a value, not an exception
+The structured no-result splits into a plain `Outcome` value (kind · discriminator · reason ·
+alternatives) and a private internal `Refusal` *signal*. `ColumnResult.refusal` now holds an
+`Outcome`: clarify/refuse/error is **data** every surface reads, never an `Exception`. 116 checks.
+
+## [0.7.5-core] — ratio/rate co-anchoring (ADR-032 D5)
+A ratio `N / D` is determinate only when numerator and denominator resolve over one shared
+population. The planner checks this statically: a cross-universe ratio is a **clarify**
+(`co_anchor_ambiguous`), naming the candidate populations, never a silent number. 115 checks.
+
+## [0.7.4-core] — the two-level correctness contract (ADR-032)
+The column engine never judges: it attempts and returns a result or a *no-result carrying a
+discriminator* (`ambiguous` / `unsupported`). The **planner** owns the four outcomes
+(serve · disclose · clarify · refuse) plus `error`, classifying every no-result at one chokepoint.
+
+## [0.7.3-core] — attribute-anchor resolution hardened
+`_attr_anchor` no longer picks the first edge a table provides: single-grain is unambiguous, a
+denormalized multi-grain table is pinned by the delivery frame, and a genuinely ambiguous case is
+**refused with the candidate levels named**. 107 checks across 10 suites.
+
+## [0.7.2-core] — universe-predicate evaluation hardened to typed predicates
+The universe predicate is evaluated at base grain by **broadcast-and-filter, never a join**;
+compared sides are coerced to a common dtype. Fixes numeric / real-`Date` predicate handling.
+101 checks across 10 suites.
+
+## [0.7.1-core] — B-anchor crossing locus refinement + EXPLAIN-without-execution
+Crossing *detection* moves from engine (execute time) to planner (compile time);
+`frame(...).plan()` / `explain(execute=False)` returns the would-be annotation touching zero
+backend data.
+
+## [0.7.0-core] — a custom type + three custom operators, planner untouched (HLL case study)
+The `distinct` family is decomposed into a parametric type `HLLSketch(p)` and three registered
+operators (`hll_count`, `hll_merge`, `hll_estimate`) that slot in via the registry + engine only;
+`planner.py` and `projection.py` hold zero sketch references. A publish-time witness store makes
+sketches **stored, not cached**.
+
+## [0.6.0-core] — inform-and-serve reconciliation (Frame-QL Manual)
+A B-anchor crossing is **served with a critical `b_anchor_crossing` disclosure** naming the
+alternative reducer, no longer refused. Disclosures carry a severity lattice
+(none < info < caution < critical) with a frame-level rollup. 57 checks across 7 suites.
+
+[0.7.7-core]: https://github.com/datumwise/columna

columna_core-0.7.8/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

columna_core-0.7.8/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: columna-core
+Version: 0.7.8
+Summary: Columna Core — the column-foundation analytic framework (multi-table, transport-based, correctness-governed) over a single backend.
+Project-URL: Homepage, https://github.com/datumwise/columna
+Project-URL: Repository, https://github.com/datumwise/columna
+Author: Datumwise
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: analytics,duckdb,frame-ql,manifold,polars,semantic-layer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: datasketches<6.0,>=5.0
+Requires-Dist: duckdb<2.0,>=1.0
+Requires-Dist: polars<2.0,>=1.0
+Requires-Dist: pyarrow>=15
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Columna Core (0.7.8-core)
+
+> **v0.7.8-core — packaging hardening + the disclosure wire adapter.** Declares the hard `pyarrow`
+> runtime dependency and resolves `COLUMNA_BENCH_WAREHOUSE` absolutely (WP-0 audit finds); reconciles
+> `benchmark.cml` with the code-built Manifold (adds `region_label`); clears the v0.7.8 worklist
+> (parser `Optional` import; unused-import / dead-local / f-string cruft). Adds
+> `columna_core.disclosure_wire` — the structured `{code, materiality, …}` wire adapter (ADR-032 D8 /
+> WP-1.3), the one contract every surface serializes. See `CHANGELOG.md`.
+
+> **v0.7.7-core — `ON UNIVERSE` pin wiring (Option A).** The population pin recorded by `Frame.on_universe(u)` is now threaded to the planner (`run`/`plan` → `_infer`), where it asserts the frame's intended population. A measure bound to `u` serves; a measure bound to a *different* universe is out-of-domain for that population and **refuses** (`out_of_universe`); an unknown `u` is an **error**. This resolves the multi-universe and D5 co-anchoring ambiguity to the one chosen population — so a cross-universe ratio that *clarifies* unpinned becomes a serve or an honest refuse once pinned, and a multi-universe frame's coverage caveat is resolved. (Resolving a measure over a universe *other* than its declared one — true cross-universe confinement — is Option B, future.) `coanchor_demo` §D covers it. 124 checks across 11 suites.
+
+> **v0.7.6-core — the no-result is a value, not an exception.** The structured no-result is split into a plain `Outcome` value (kind · discriminator · reason · alternatives) and a private internal `Refusal` *signal* that merely carries it from deep in the recursive walk to the planner's single assembly point. `ColumnResult.refusal` now holds an `Outcome`: a clarify/refuse/error is **data** every surface and agent reads, never an `Exception` a caller could swallow with `except Exception`. (`Refusal` remains the internal control-flow goto; eliminating even that would mean return-threading the recursive type-inferencer — deliberately not done.) `coanchor_demo` asserts the clarify is an `Outcome`, not an exception. 116 checks across 11 suites.
+
+> **v0.7.5-core — ratio/rate co-anchoring (ADR-032 D5).** A ratio `N / D` is determinate only when numerator and denominator resolve over one shared population. The planner now checks this statically: a ratio whose operands span different universes is a **clarify** (`co_anchor_ambiguous`, discriminator `ambiguous`) naming the candidate populations — "which population is the rate over?" — never a silent number. It is *not* eager (a same-universe ratio, or a constant denominator, just serves) and is distinct from avg-of-averages (a B-anchor hazard). Scoped to the ratio: the same two measures as *separate columns* still serve with the multi-universe coverage caveat. New `coanchor_demo`; 115 checks across 11 suites.
+
+> **v0.7.4-core — the two-level correctness contract (ADR-032).** The column engine never judges: it attempts and returns either a result or a *no-result carrying a discriminator* — `ambiguous` (no unique answer under the rules) or `unsupported` (the data can't support a result). The **planner** owns the four outcomes (serve · disclose · clarify · refuse), plus `error` for vocabulary/capability failures, and classifies every no-result at one chokepoint (`Refusal.classified`). The multi-grain attribute case is now a **clarify** (ambiguous), not an `unknown` error lumped with real failures; out-of-universe is a **refuse**; an unimplemented operator is an **error**. `FrameResult.outcome / .clarifies / .refusals / .errors` surface the verdicts; `confine_demo` verifies the classification.
+
+> **v0.7.3-core — attribute-anchor resolution hardened.** When a universe predicate references an attribute `T.col`, the engine must broadcast it at the level `T` is keyed. `_attr_anchor` no longer picks the first edge `T` provides: a single-grain table is unambiguous, a denormalized multi-grain table (one `geo` table providing `store→region` *and* `region→country`) is **pinned by the delivery frame**, and a genuinely ambiguous case is **refused with the candidate levels named** — never a silent wrong grain. `confine_demo` proves the pin and the refusal. 107 checks across 10 suites.
+
+> **v0.7.2-core — universe-predicate evaluation hardened to typed predicates.** The universe predicate is evaluated at the base grain by **broadcast-and-filter, never a join**: each referenced attribute is delivered single-table and broadcast onto the frame along its key (transport), the compared sides are **coerced to a common dtype**, and the frame is filtered. Fixes a real gap — a numeric (`qty >= 10`) or real-`Date` predicate previously raised a dtype error because predicate literals arrive as strings, and only the benchmark's ISO-date *strings* compared correctly by luck. `confine_demo` now proves numeric / Date / AND-ed predicates alongside out-of-domain exclusion. 101 checks across 10 suites.
+
+> **v0.7.1-core — B-anchor crossing locus refinement + EXPLAIN-without-execution.** Crossing *detection* moved from the engine (execute time) to the planner (compile time): `blocked_lineages` and the operator's `is_monoid` are now surfaced on the shape projection, so a crossing is knowable from structure alone. The served contract is unchanged (still served-with-critical, never refused), but `frame(...).plan()` / `explain(execute=False)` returns the would-be annotation — the critical crossing plus spec-only provenance caveats — touching **zero backend data**.
+
+> **v0.7.0-core — a custom type + three custom operators, planner untouched (HLL case study).** The `distinct` family is decomposed into a parametric type `HLLSketch(p)` and three registered operators — `hll_count` (deliver), `hll_merge` (a monoid union, combine), `hll_estimate` (project) — that slot into the umbrella via the **registry and engine only**; `planner.py` and `projection.py` hold zero sketch references. Precision is type identity (a mismatched merge is a type error; a raw sketch is opaque to arithmetic). A publish-time **witness store** makes sketches **stored, not cached**, so `distinct@region` merges stored witnesses with **zero base scans at query time**.
+
+> **v0.6.0-core — inform-and-serve reconciliation (Frame-QL Manual).** A B-anchor crossing (e.g. summing a stock over time) is now **served with a critical `b_anchor_crossing` disclosure** that names the alternative reducer — no longer refused. Refusals are reserved for the planner's static clarify/inform cases (fan-out across an M:N edge — now naming all three remedies; out-of-universe; unknown operator; type error). The engine, once handed an executable atom, never withholds on analytical grounds. Disclosures now carry a severity lattice (none<info<caution<critical) with a frame-level rollup. 57 checks across 7 suites pass.
+
+
+The column-foundation implementation specified in **ADR-031** and the **Manifold object model** — multi-table, transport-based, validated against the real benchmark warehouse (299,934 transactions).
+
+This is **not** the ADR-030 kernel. The kernel proved correctness *techniques* on a single denormalized table; Core implements the architecture: **the backend delivers single-table column-atoms and functional relationship-columns; the engine *transports* and relates them; the backend never joins.**
+
+## The discipline, in code
+
+- `connector.py` — **single-table delivery only.** `deliver_measure` (one-table group-by), `deliver_edge` (one-table key→key mapping), `deliver_base_rows` (one-table, for sketches). No SQL join is ever generated.
+- `model.py` — the Manifold object model. Two layers: **universes** (populations) and the **coordinate DAG** (`FunctionalEdge`s). A rollup (`day→month`) and a relationship (`store→region`) are the *same* object — a functional edge the engine transports along, tagged with a lineage. The **B-anchor** blocks per-lineage.
+- `engine.py` — the center. For `(measure, family-member) @ anchor`: find the functional path, **B-anchor-check every transport edge *and* every collapsed dimension**, resolve cheapest-faithful (cache vs delivery), **transport** the measure along functional edges (in-engine; no join pushdown), co-compute disclosure, cache.
+- `planner.py` — provenance-blind. Parses logical `family.member @ anchor`, expands derived columns, **typechecks addressability — fan-out and out-of-universe are refused HERE, statically** — then assembles frames and folds disclosures.
+- `disclosure.py` — the disclosure shadow-value and its sibling, the structured, dialog-capable `Refusal` (carries named alternatives).
+
+## What `build_benchmark.py` proves (10/10, real data)
+
+1. **Transport replaces the join** — `revenue@region` computed from a single-table `revenue@store` delivery + the `store→region` mapping, related *in the engine*; exact vs. ground truth; **zero joins pushed down**.
+2. **Coordinate rollup is the same operation** — `revenue@cal.month` via the `day→month` mapping.
+3. **★ Fan-out is inexpressible ★** — `revenue@category` is **refused** at the planner (`transaction↔category` is M:N); for contrast, the naive join *silently inflates revenue 1.44× — a 44% overcount*. The refusal names its alternatives (allocation = Pro; membership = rephrase). The flagship.
+4. **B-anchor blocks per-lineage** — `level.sum@(region,day)` *works* (additive over the store axis); `level.sum@store` is *refused* (would sum a stock across days — non-reconciling over the calendar lineage). Same metric, opposite verdicts, by edge.
+5. **Pre/post-agg boundary** — `aov = revenue/orders` computed post-aggregation = correct AOV (not the avg-of-avgs the shipped `monthly_avg_order_value` would give).
+6. **Sketch reaggregation** — `visitors@cal.quarter` by HLL-merging per-day sketches; ≈ true distinct, vs. a naive sum-of-daily-distincts that overcounts.
+7. **Out-of-universe** — `level@product` refused as a *distinct* reason (out of domain — undefined, not missing).
+
+```
+engine: 5 single-table deliveries, 5 transports, 1 cache-hit, 10 backend fetches (all single-table)
+```
+
+## Run
+
+```bash
+pip install --break-system-packages polars duckdb datasketches pyarrow
+python3 build_benchmark.py     # 10 checks against the benchmark warehouse
+```
+(The script reads the warehouse parquets from the benchmark instance path; adjust `WAREHOUSE` if needed.)
+
+## Ingest-first: the definition language
+
+A written `MANIFOLD` definition (the `.cf` successor) parses to the Manifold object and is queryable end-to-end — no hand-construction. See `benchmark.cml` for the whole benchmark Manifold as text, and run:
+
+```bash
+python3 parse_benchmark.py     # parse benchmark.cml, then the SAME 10 checks on the PARSED Manifold
+```
+
+The parser (`parser.py`) reproduces the hand-built object with full structural parity, the corrected semantics survive the parse (`M_ANCHOR { }` → MCAR; `FAMILY { sum : additive BLOCKED { calendar } }` → per-member B-anchor), and publish-time well-formedness checks reject malformed definitions (impure predicate referencing a measure, unknown level/universe/column, etc.).
+
+Grammar (statement-oriented; `#` comments; `{ }` blocks):
+```
+MANIFOLD <name> VERSION <n>
+UNIVERSE <name> = <dim> * <dim> ... [WHERE <predicate>]
+LEVEL <name> = <column> [BASE]
+EDGE <from> -> <to> ALONG <lineage> VIA <table>(<from_col>, <to_col>)
+RELATE <a> <-> <b> VIA <table> [NOTE "<text>"]
+MEASURE <name> ON <universe> FROM <table> AS <agg>(<expr>)
+MEASURE <name> ON <universe> FROM <table> VALUE <expr>
+    [M_ANCHOR { <col>, ... }] [FAMILY { <agg> [: <tier>] [BLOCKED { <lineage>, ... }] ... }]
+DERIVED <name> = <expr>
+```
+
+## Scope (Core, per ADR-031)
+
+**Logical types, checked at compile time** (`types.py`, `types_demo.py`): every measure declares a **logical (Polars) dtype** and every operator carries a **type signature** (`sum: Numeric∪Duration→same`, `distinct: any→Int64`, `median: Numeric∪Temporal→same`, `last: T→T`). The *signature* is vocabulary the planner holds; the *mechanics* (witness/combine/deliver_sql) stay engine-side. So "operator not supported" and "wrong type for this operator" are **vocabulary errors caught at the planner, before the engine is ever asked** — proven by zero backend fetches on a refused frame. A static type-inference pass runs as a compile step ahead of resolution (`type_error` is its refusal reason, a sibling of unknown-operator). The **connector owns logical→physical**: a measure declares logical `Float64` over a raw column, and the connector supplies the `TRY_CAST` when the physical type is a dirty `VARCHAR` — so the author writes no casts, and a cast *failure* is a coverage fact at resolution, never a type error.
+
+In scope and working: multi-table Manifolds, universes **with runtime predicate confinement**, the coordinate DAG, transport, measure-families with per-lineage B-anchors, **the operator registry (reaggregation as a monoid property, plus type signatures)**, **logical types with a compile-time planner typecheck**, derived columns, structured refusals, EXPLAIN, the definition-language parser + well-formedness checks, **the universe-support consistency check**, **the two projections as an enforced boundary**. Deliberately out (Pro): multiple backends/federation, cloud, custom operators/types, sophisticated optimization, **allocation** (the M:N split — Core catches the case rather than computing it).
+
+**Two projections, enforced** (`projection.py`, `projection_demo.py`): one authored Manifold has two projections. The **planner** holds a `PlannerView` — vocabulary/shape only: logical names, the DAG *topology* (`frm→to` + lineage, no physical columns), family member *names*, derived formulas, M:N pairs for fan-out. The **engine** holds the full Manifold — sources, realizations, the universe predicate, missingness, costs, the operator registry. This makes "the planner cannot see provenance" *structural*: `home_table`, `pre_expr`, `realized_by`, `provider_table`, and the predicate are simply absent from the planner's object — no source string is reachable from it — yet it still does real work (fan-out and out-of-universe are refused from shape alone). The handoff down is a logical request `(measure, member, anchor)`; the return up is a frame + a `Disclosure` (caveats, not sources). Disclosures cross the boundary; provenance does not.
+
+**Reaggregation is a monoid property of the operator** (`operators.py` — the registry, which is the Core/Pro extension point). An operator is reaggregable iff a possibly-enriched witness makes it a monoid; the engine reduces in *witness-space* and projects to the answer at the boundary: `sum`/`count` carry the value (combine `+`), `min`/`max` the value (combine min/max), `distinct` an HLL sketch (combine union), `last`/`first` the **(value, order_key)** pair (combine argmax/argmin — the order key is carried as the witness), and `median`/`mode` are **holistic** (no finite witness → recompute-from-base, never reduced). Two independent gates compose: **monoid-ness** (operator-level, *possible*) and the **B-anchor** (column-level, *permitted*). The headline (`holistic_demo.py`): `level.last@(store, cal.month)` *works* by carrying the day and reducing by argmax, while `level.sum@(store, cal.month)` *refuses* — same column, same target, the two gates disagree.
+
+**Universe-support consistency** (`universe_check_demo.py`): a universe is one population, so every measure bound to it must reduce to the same base-point support (modulo declared coverage). The check reduces each measure to its universe and compares supports; a mismatch not explained by coverage flags a mis-declared universe. (Benchmark passes; a measure mis-sourced from a half-coverage table is flagged "50% short".) This is the **count-reducer instance** of a more general *path-independence* check — reduce a measure to the universe singleton along every anchoring and assert the reduced values agree — which becomes exercisable once a second coordinatization of an axis (e.g. a fiscal calendar forking from `day`) exists; with a single anchoring there is nothing to reconcile against.
+
+**Universe-predicate confinement** (`confine_demo.py`): a measure bound to a predicated universe is confined to its valid points *at the base grain, at delivery, before aggregation* — logically prior to any query `WHERE` (domain before selection), inherited through cache and transport. A cross-table predicate like `day >= stores.opened_date` is evaluated *in the engine*: `opened_date` is delivered from `stores` (single table) and **broadcast** onto `(store, day)` by transport, then compared and filtered — **never a backend join**. The demo injects out-of-domain rows; the engine excludes them while an unconfined Manifold silently includes them.
+
+Still thin in this build (next): the full cached-vs-stored cost search (resolution is correct but the cost model is minimal); hoisting the **B-anchor permission** refusal (`blocked_reaggregation`) from the engine to the planner (it is structural and belongs there, but it currently sits in the engine to preserve behaviour — moving it means the `PlannerView` carries family-member shape); automated Discovery (the parser consumes a written definition; generating one from a warehouse is the layer above).

columna_core-0.7.8/README.md

@@ -0,0 +1,100 @@
+# Columna Core (0.7.8-core)
+
+> **v0.7.8-core — packaging hardening + the disclosure wire adapter.** Declares the hard `pyarrow`
+> runtime dependency and resolves `COLUMNA_BENCH_WAREHOUSE` absolutely (WP-0 audit finds); reconciles
+> `benchmark.cml` with the code-built Manifold (adds `region_label`); clears the v0.7.8 worklist
+> (parser `Optional` import; unused-import / dead-local / f-string cruft). Adds
+> `columna_core.disclosure_wire` — the structured `{code, materiality, …}` wire adapter (ADR-032 D8 /
+> WP-1.3), the one contract every surface serializes. See `CHANGELOG.md`.
+
+> **v0.7.7-core — `ON UNIVERSE` pin wiring (Option A).** The population pin recorded by `Frame.on_universe(u)` is now threaded to the planner (`run`/`plan` → `_infer`), where it asserts the frame's intended population. A measure bound to `u` serves; a measure bound to a *different* universe is out-of-domain for that population and **refuses** (`out_of_universe`); an unknown `u` is an **error**. This resolves the multi-universe and D5 co-anchoring ambiguity to the one chosen population — so a cross-universe ratio that *clarifies* unpinned becomes a serve or an honest refuse once pinned, and a multi-universe frame's coverage caveat is resolved. (Resolving a measure over a universe *other* than its declared one — true cross-universe confinement — is Option B, future.) `coanchor_demo` §D covers it. 124 checks across 11 suites.
+
+> **v0.7.6-core — the no-result is a value, not an exception.** The structured no-result is split into a plain `Outcome` value (kind · discriminator · reason · alternatives) and a private internal `Refusal` *signal* that merely carries it from deep in the recursive walk to the planner's single assembly point. `ColumnResult.refusal` now holds an `Outcome`: a clarify/refuse/error is **data** every surface and agent reads, never an `Exception` a caller could swallow with `except Exception`. (`Refusal` remains the internal control-flow goto; eliminating even that would mean return-threading the recursive type-inferencer — deliberately not done.) `coanchor_demo` asserts the clarify is an `Outcome`, not an exception. 116 checks across 11 suites.
+
+> **v0.7.5-core — ratio/rate co-anchoring (ADR-032 D5).** A ratio `N / D` is determinate only when numerator and denominator resolve over one shared population. The planner now checks this statically: a ratio whose operands span different universes is a **clarify** (`co_anchor_ambiguous`, discriminator `ambiguous`) naming the candidate populations — "which population is the rate over?" — never a silent number. It is *not* eager (a same-universe ratio, or a constant denominator, just serves) and is distinct from avg-of-averages (a B-anchor hazard). Scoped to the ratio: the same two measures as *separate columns* still serve with the multi-universe coverage caveat. New `coanchor_demo`; 115 checks across 11 suites.
+
+> **v0.7.4-core — the two-level correctness contract (ADR-032).** The column engine never judges: it attempts and returns either a result or a *no-result carrying a discriminator* — `ambiguous` (no unique answer under the rules) or `unsupported` (the data can't support a result). The **planner** owns the four outcomes (serve · disclose · clarify · refuse), plus `error` for vocabulary/capability failures, and classifies every no-result at one chokepoint (`Refusal.classified`). The multi-grain attribute case is now a **clarify** (ambiguous), not an `unknown` error lumped with real failures; out-of-universe is a **refuse**; an unimplemented operator is an **error**. `FrameResult.outcome / .clarifies / .refusals / .errors` surface the verdicts; `confine_demo` verifies the classification.
+
+> **v0.7.3-core — attribute-anchor resolution hardened.** When a universe predicate references an attribute `T.col`, the engine must broadcast it at the level `T` is keyed. `_attr_anchor` no longer picks the first edge `T` provides: a single-grain table is unambiguous, a denormalized multi-grain table (one `geo` table providing `store→region` *and* `region→country`) is **pinned by the delivery frame**, and a genuinely ambiguous case is **refused with the candidate levels named** — never a silent wrong grain. `confine_demo` proves the pin and the refusal. 107 checks across 10 suites.
+
+> **v0.7.2-core — universe-predicate evaluation hardened to typed predicates.** The universe predicate is evaluated at the base grain by **broadcast-and-filter, never a join**: each referenced attribute is delivered single-table and broadcast onto the frame along its key (transport), the compared sides are **coerced to a common dtype**, and the frame is filtered. Fixes a real gap — a numeric (`qty >= 10`) or real-`Date` predicate previously raised a dtype error because predicate literals arrive as strings, and only the benchmark's ISO-date *strings* compared correctly by luck. `confine_demo` now proves numeric / Date / AND-ed predicates alongside out-of-domain exclusion. 101 checks across 10 suites.
+
+> **v0.7.1-core — B-anchor crossing locus refinement + EXPLAIN-without-execution.** Crossing *detection* moved from the engine (execute time) to the planner (compile time): `blocked_lineages` and the operator's `is_monoid` are now surfaced on the shape projection, so a crossing is knowable from structure alone. The served contract is unchanged (still served-with-critical, never refused), but `frame(...).plan()` / `explain(execute=False)` returns the would-be annotation — the critical crossing plus spec-only provenance caveats — touching **zero backend data**.
+
+> **v0.7.0-core — a custom type + three custom operators, planner untouched (HLL case study).** The `distinct` family is decomposed into a parametric type `HLLSketch(p)` and three registered operators — `hll_count` (deliver), `hll_merge` (a monoid union, combine), `hll_estimate` (project) — that slot into the umbrella via the **registry and engine only**; `planner.py` and `projection.py` hold zero sketch references. Precision is type identity (a mismatched merge is a type error; a raw sketch is opaque to arithmetic). A publish-time **witness store** makes sketches **stored, not cached**, so `distinct@region` merges stored witnesses with **zero base scans at query time**.
+
+> **v0.6.0-core — inform-and-serve reconciliation (Frame-QL Manual).** A B-anchor crossing (e.g. summing a stock over time) is now **served with a critical `b_anchor_crossing` disclosure** that names the alternative reducer — no longer refused. Refusals are reserved for the planner's static clarify/inform cases (fan-out across an M:N edge — now naming all three remedies; out-of-universe; unknown operator; type error). The engine, once handed an executable atom, never withholds on analytical grounds. Disclosures now carry a severity lattice (none<info<caution<critical) with a frame-level rollup. 57 checks across 7 suites pass.
+
+
+The column-foundation implementation specified in **ADR-031** and the **Manifold object model** — multi-table, transport-based, validated against the real benchmark warehouse (299,934 transactions).
+
+This is **not** the ADR-030 kernel. The kernel proved correctness *techniques* on a single denormalized table; Core implements the architecture: **the backend delivers single-table column-atoms and functional relationship-columns; the engine *transports* and relates them; the backend never joins.**
+
+## The discipline, in code
+
+- `connector.py` — **single-table delivery only.** `deliver_measure` (one-table group-by), `deliver_edge` (one-table key→key mapping), `deliver_base_rows` (one-table, for sketches). No SQL join is ever generated.
+- `model.py` — the Manifold object model. Two layers: **universes** (populations) and the **coordinate DAG** (`FunctionalEdge`s). A rollup (`day→month`) and a relationship (`store→region`) are the *same* object — a functional edge the engine transports along, tagged with a lineage. The **B-anchor** blocks per-lineage.
+- `engine.py` — the center. For `(measure, family-member) @ anchor`: find the functional path, **B-anchor-check every transport edge *and* every collapsed dimension**, resolve cheapest-faithful (cache vs delivery), **transport** the measure along functional edges (in-engine; no join pushdown), co-compute disclosure, cache.
+- `planner.py` — provenance-blind. Parses logical `family.member @ anchor`, expands derived columns, **typechecks addressability — fan-out and out-of-universe are refused HERE, statically** — then assembles frames and folds disclosures.
+- `disclosure.py` — the disclosure shadow-value and its sibling, the structured, dialog-capable `Refusal` (carries named alternatives).
+
+## What `build_benchmark.py` proves (10/10, real data)
+
+1. **Transport replaces the join** — `revenue@region` computed from a single-table `revenue@store` delivery + the `store→region` mapping, related *in the engine*; exact vs. ground truth; **zero joins pushed down**.
+2. **Coordinate rollup is the same operation** — `revenue@cal.month` via the `day→month` mapping.
+3. **★ Fan-out is inexpressible ★** — `revenue@category` is **refused** at the planner (`transaction↔category` is M:N); for contrast, the naive join *silently inflates revenue 1.44× — a 44% overcount*. The refusal names its alternatives (allocation = Pro; membership = rephrase). The flagship.
+4. **B-anchor blocks per-lineage** — `level.sum@(region,day)` *works* (additive over the store axis); `level.sum@store` is *refused* (would sum a stock across days — non-reconciling over the calendar lineage). Same metric, opposite verdicts, by edge.
+5. **Pre/post-agg boundary** — `aov = revenue/orders` computed post-aggregation = correct AOV (not the avg-of-avgs the shipped `monthly_avg_order_value` would give).
+6. **Sketch reaggregation** — `visitors@cal.quarter` by HLL-merging per-day sketches; ≈ true distinct, vs. a naive sum-of-daily-distincts that overcounts.
+7. **Out-of-universe** — `level@product` refused as a *distinct* reason (out of domain — undefined, not missing).
+
+```
+engine: 5 single-table deliveries, 5 transports, 1 cache-hit, 10 backend fetches (all single-table)
+```
+
+## Run
+
+```bash
+pip install --break-system-packages polars duckdb datasketches pyarrow
+python3 build_benchmark.py     # 10 checks against the benchmark warehouse
+```
+(The script reads the warehouse parquets from the benchmark instance path; adjust `WAREHOUSE` if needed.)
+
+## Ingest-first: the definition language
+
+A written `MANIFOLD` definition (the `.cf` successor) parses to the Manifold object and is queryable end-to-end — no hand-construction. See `benchmark.cml` for the whole benchmark Manifold as text, and run:
+
+```bash
+python3 parse_benchmark.py     # parse benchmark.cml, then the SAME 10 checks on the PARSED Manifold
+```
+
+The parser (`parser.py`) reproduces the hand-built object with full structural parity, the corrected semantics survive the parse (`M_ANCHOR { }` → MCAR; `FAMILY { sum : additive BLOCKED { calendar } }` → per-member B-anchor), and publish-time well-formedness checks reject malformed definitions (impure predicate referencing a measure, unknown level/universe/column, etc.).
+
+Grammar (statement-oriented; `#` comments; `{ }` blocks):
+```
+MANIFOLD <name> VERSION <n>
+UNIVERSE <name> = <dim> * <dim> ... [WHERE <predicate>]
+LEVEL <name> = <column> [BASE]
+EDGE <from> -> <to> ALONG <lineage> VIA <table>(<from_col>, <to_col>)
+RELATE <a> <-> <b> VIA <table> [NOTE "<text>"]
+MEASURE <name> ON <universe> FROM <table> AS <agg>(<expr>)
+MEASURE <name> ON <universe> FROM <table> VALUE <expr>
+    [M_ANCHOR { <col>, ... }] [FAMILY { <agg> [: <tier>] [BLOCKED { <lineage>, ... }] ... }]
+DERIVED <name> = <expr>
+```
+
+## Scope (Core, per ADR-031)
+
+**Logical types, checked at compile time** (`types.py`, `types_demo.py`): every measure declares a **logical (Polars) dtype** and every operator carries a **type signature** (`sum: Numeric∪Duration→same`, `distinct: any→Int64`, `median: Numeric∪Temporal→same`, `last: T→T`). The *signature* is vocabulary the planner holds; the *mechanics* (witness/combine/deliver_sql) stay engine-side. So "operator not supported" and "wrong type for this operator" are **vocabulary errors caught at the planner, before the engine is ever asked** — proven by zero backend fetches on a refused frame. A static type-inference pass runs as a compile step ahead of resolution (`type_error` is its refusal reason, a sibling of unknown-operator). The **connector owns logical→physical**: a measure declares logical `Float64` over a raw column, and the connector supplies the `TRY_CAST` when the physical type is a dirty `VARCHAR` — so the author writes no casts, and a cast *failure* is a coverage fact at resolution, never a type error.
+
+In scope and working: multi-table Manifolds, universes **with runtime predicate confinement**, the coordinate DAG, transport, measure-families with per-lineage B-anchors, **the operator registry (reaggregation as a monoid property, plus type signatures)**, **logical types with a compile-time planner typecheck**, derived columns, structured refusals, EXPLAIN, the definition-language parser + well-formedness checks, **the universe-support consistency check**, **the two projections as an enforced boundary**. Deliberately out (Pro): multiple backends/federation, cloud, custom operators/types, sophisticated optimization, **allocation** (the M:N split — Core catches the case rather than computing it).
+
+**Two projections, enforced** (`projection.py`, `projection_demo.py`): one authored Manifold has two projections. The **planner** holds a `PlannerView` — vocabulary/shape only: logical names, the DAG *topology* (`frm→to` + lineage, no physical columns), family member *names*, derived formulas, M:N pairs for fan-out. The **engine** holds the full Manifold — sources, realizations, the universe predicate, missingness, costs, the operator registry. This makes "the planner cannot see provenance" *structural*: `home_table`, `pre_expr`, `realized_by`, `provider_table`, and the predicate are simply absent from the planner's object — no source string is reachable from it — yet it still does real work (fan-out and out-of-universe are refused from shape alone). The handoff down is a logical request `(measure, member, anchor)`; the return up is a frame + a `Disclosure` (caveats, not sources). Disclosures cross the boundary; provenance does not.
+
+**Reaggregation is a monoid property of the operator** (`operators.py` — the registry, which is the Core/Pro extension point). An operator is reaggregable iff a possibly-enriched witness makes it a monoid; the engine reduces in *witness-space* and projects to the answer at the boundary: `sum`/`count` carry the value (combine `+`), `min`/`max` the value (combine min/max), `distinct` an HLL sketch (combine union), `last`/`first` the **(value, order_key)** pair (combine argmax/argmin — the order key is carried as the witness), and `median`/`mode` are **holistic** (no finite witness → recompute-from-base, never reduced). Two independent gates compose: **monoid-ness** (operator-level, *possible*) and the **B-anchor** (column-level, *permitted*). The headline (`holistic_demo.py`): `level.last@(store, cal.month)` *works* by carrying the day and reducing by argmax, while `level.sum@(store, cal.month)` *refuses* — same column, same target, the two gates disagree.
+
+**Universe-support consistency** (`universe_check_demo.py`): a universe is one population, so every measure bound to it must reduce to the same base-point support (modulo declared coverage). The check reduces each measure to its universe and compares supports; a mismatch not explained by coverage flags a mis-declared universe. (Benchmark passes; a measure mis-sourced from a half-coverage table is flagged "50% short".) This is the **count-reducer instance** of a more general *path-independence* check — reduce a measure to the universe singleton along every anchoring and assert the reduced values agree — which becomes exercisable once a second coordinatization of an axis (e.g. a fiscal calendar forking from `day`) exists; with a single anchoring there is nothing to reconcile against.
+
+**Universe-predicate confinement** (`confine_demo.py`): a measure bound to a predicated universe is confined to its valid points *at the base grain, at delivery, before aggregation* — logically prior to any query `WHERE` (domain before selection), inherited through cache and transport. A cross-table predicate like `day >= stores.opened_date` is evaluated *in the engine*: `opened_date` is delivered from `stores` (single table) and **broadcast** onto `(store, day)` by transport, then compared and filtered — **never a backend join**. The demo injects out-of-domain rows; the engine excludes them while an unconfined Manifold silently includes them.
+
+Still thin in this build (next): the full cached-vs-stored cost search (resolution is correct but the cost model is minimal); hoisting the **B-anchor permission** refusal (`blocked_reaggregation`) from the engine to the planner (it is structural and belongs there, but it currently sits in the engine to preserve behaviour — moving it means the `PlannerView` carries family-member shape); automated Discovery (the parser consumes a written definition; generating one from a warehouse is the layer above).

columna_core-0.7.8/demos/benchmark.cml

@@ -0,0 +1,61 @@
+MANIFOLD benchmark VERSION 1
+
+# ============================================================================
+# Layer 1 — populations (universes).  predicate carves the real population.
+# ============================================================================
+UNIVERSE transactions = customer * store * product * day
+UNIVERSE store_days   = store * day  WHERE day >= stores.opened_date
+
+# ============================================================================
+# Layer 2 — coordinate.  Base levels, then functional edges.
+# A rollup (day->month) and a relationship (store->region) are the SAME thing:
+# a functional edge the engine transports along, tagged with a lineage.
+# ============================================================================
+LEVEL customer    = customer_id BASE
+LEVEL store       = store_id    BASE
+LEVEL product     = product_id  BASE
+LEVEL day         = day         BASE
+LEVEL region      = region
+LEVEL cal.week    = week
+LEVEL cal.month   = month
+LEVEL cal.quarter = quarter
+LEVEL cal.year    = year
+LEVEL category    = category_id
+
+EDGE store -> region      ALONG store_geo VIA stores(store_id, region)
+EDGE day   -> cal.week    ALONG calendar  VIA calendar(day, week)
+EDGE day   -> cal.month   ALONG calendar  VIA calendar(day, month)
+EDGE day   -> cal.quarter ALONG calendar  VIA calendar(day, quarter)
+EDGE day   -> cal.year    ALONG calendar  VIA calendar(day, year)
+
+# non-functional (M:N) — declared only so a fan-out refusal can name the edge.
+RELATE product <-> category VIA product_categories NOTE "a product belongs to up to 3 categories"
+
+# ============================================================================
+# Measures.  Inline AS for single-member families; VALUE + FAMILY for multi.
+# ============================================================================
+MEASURE revenue  ON transactions FROM transactions AS sum(amount)
+MEASURE orders   ON transactions FROM transactions AS count(*)
+MEASURE visitors ON transactions FROM transactions AS distinct(customer_id)
+
+# semi-additive stock.  sum: blocked over calendar (totalling stock across time is
+# non-reconciling).  last: an ORDERED monoid over day (carry day as witness) — the
+# period-end snapshot is the point, so last is NOT blocked over calendar.
+# Tier (additive/sketch/holistic) is NOT declared here: it is operator-level, from the registry.
+MEASURE level ON store_days FROM eom_inventory VALUE level
+    M_ANCHOR { }
+    FAMILY {
+        sum  BLOCKED { calendar }
+        last ORDER day
+    }
+
+# holistic measure: median basket amount — non-monoid, recompute-from-base, never reduced
+MEASURE med_amount ON transactions FROM transactions AS median(amount)
+
+# a CATEGORICAL measure — only count/distinct/mode are well-typed over it (never sum/median)
+MEASURE region_label ON transactions FROM transactions AS mode(customer_region)
+
+# ============================================================================
+# Derived columns — post-aggregation over measures.
+# ============================================================================
+DERIVED aov = revenue / orders