terrine 0.1.0.dev1__tar.gz → 0.1.0.dev2__tar.gz

{terrine-0.1.0.dev1 → terrine-0.1.0.dev2}/CHANGELOG.md

@@ -1,5 +1,164 @@
 # Changelog
 
+## 0.1.0.dev2
+
+### Performance
+
+- Run a build's integrity checks, eligibility summary and output in one
+  statement. Window checks are boolean flag columns of the study's audit
+  relation instead of one statement per check that recomputed the metric
+  from the source tables; the deferred checks form one schedule in
+  registration order, folded into gate statements, and the final run's
+  counts and the eligibility summary ride on the output statement as a
+  one-row cross join that is decoded before the first batch leaves. Refusal
+  codes, their context (`failed_count` included) and the first refusal for a
+  given dataset are unchanged; an empty output still refuses a failing check
+  on an excluded candidate, and `Budget.max_rows` and `max_output_bytes`
+  count output rows and bytes only. On the repro (DuckDB 1.5.6; 10,000
+  units, 300,000 events, ten snapshots, three metrics; Apple M3 Pro, 12
+  cores) a warm build went from 14.0 s and eight statements over the source
+  tables to 0.8 s and one. Designs with as-of attributes or event-history
+  checks keep one statement per such check between gate statements.
+  Composition for runtime staging runs the schedule once and each staging
+  task reads its output with the summary alone;
+  `preview(..., bounded_count=N)` still runs every check unrestricted and
+  caps only its eligibility read.
+- Compare DuckDB lookup timestamps natively: a microsecond cutoff and state
+  are their own as-of keys, a naive side is attached to UTC explicitly so
+  the session `TimeZone` cannot shift it, and a nanosecond axis keeps the
+  structured order key. Hold counts in native integers there: `BIGINT` 0/1
+  terms accumulated in `HUGEINT` and narrowed by `TRY_CAST`, so a count
+  beyond `int64` refuses `terrine.temporal.exact_overflow` rather than
+  wrapping; integer, decimal and float sums keep their `BIGNUM`
+  coefficients. A window's state carries only the fields its measure reads,
+  and an unfiltered measure's state no longer holds the five constant
+  unknown-filter counters. PostgreSQL, BigQuery, Snowflake and the portable
+  policy keep their numeric and timestamp state; their compiled statements
+  change only in the gate shape, the pruned state columns and integer count
+  literals.
+
+### Breaking changes
+
+- Catalog documents are `schema_version: 2`. Sources use `time`, `units` and
+  `events`; the root event mapping is `events`; dimensions use `unit` and `key`,
+  measures use `event`, and metrics use `unit`. Version 1 catalogs refuse with
+  `terrine.catalog.invalid_definition` before other field diagnostics.
+- Design and `DatasetDefinition` documents are version 2. Older saved designs,
+  definitions, and manifests or saved plans embedding them refuse; reconstruct
+  and save the design again. Manifest and saved-plan envelope versions stay 1.
+- `Events(table, *, time, key, unit=None, metrics=None, labels=(), complete=None)`
+  replaces `keys=` and `values=` with one unit key and user-named metrics.
+  Generated metric names are removed; without `metrics=`, only the event is
+  declared. Labels, histories and events share a namespace, `__` is reserved
+  in labels, and `<source>_<column>` value-event names are reserved against
+  event, label and history declarations.
+- `Model.from_tables` drops `readiness=` and takes completeness from each
+  `Events.complete` and `History.complete`; `con` is optional for in-memory
+  tables. `Model.from_catalog` retains `readiness=`.
+- Event selectors and returned sequence metadata use `event`, not `fact`.
+  `Initiation` and `PersistentAdoption` take an event or label name without
+  `source`; its declaring source is resolved from the model.
+- Calendar-date `Schedule.end` and `AnchorRange.end` are inclusive, so the same
+  literal bounds can produce additional anchors. Aware datetime ends remain
+  exact exclusive instants; relative windows and `TimeSplit` are unchanged.
+- `Schedule.every` is `int | None`; calendar schedules set `months` instead.
+  Serialized schedules carry both fields with exactly one non-null value.
+- Every recipe and `Design` can omit `unit` for a single-unit model.
+  `life_table(group_by={name: expression})` replaces `features=`.
+  `state_panel(periods=None)` derives whole periods from the schedule; an
+  explicit period count is a cap, not permission to truncate.
+- Bound descriptors use `time_column`, `units`, `events`, `unit`,
+  `unit_columns`, `event` and `key`. Definition-hash payloads use the same
+  vocabulary, changing feature definition hashes and `Model.model_hash`.
+- The refusal codes `terrine.model.generated_metric_collision` and
+  `terrine.model.multiple_event_units` are removed.
+- Invalid constructor inputs now raise coded `TerrineError` (still a
+  `ValueError`) rather than bare `ValueError`, `TypeError`, `RuntimeError` or
+  `FileExistsError`. Context names the caller's parameter in `field` and uses
+  stable `reason` tokens; document decoders preserve a reconstructed record's
+  refusal. Pydantic records retain `ValidationError`. Agent tools expose the
+  same design and split refusal codes as direct callers.
+- DuckDB output order may differ from anchor order for small studies; row
+  order is not a dataset contract. Sort explicitly when needed.
+- New DuckDB runtime prefix layers store counts as Arrow `decimal128(38, 0)`
+  and cannot be read by older versions; older layers still restore and compose.
+
+### Public API
+
+- Declare metrics with `tr.count`, `tr.sum`, `tr.mean` (per event or
+  `per="day"`), `tr.min`, `tr.max`, `tr.count_distinct` and `tr.ratio`.
+  Their `where=` mappings accept declared labels, scalar equality, list
+  membership, and `__ne`, `__in`, `__not_in`, `__gt`, `__gte`, `__lt`,
+  `__lte` and `__between`; multiple keys are a conjunction.
+- `Events(labels=...)` binds typed event-time properties for filters,
+  `event_time`, `asof` and treatment. `History` binds as-of attributes through
+  range validity (`valid_from`, optional `valid_to`) or a change log
+  (`changed_at`) in `Model.from_tables(history=...)`.
+- `UnitSource`, `Events` and `History` accept pandas/Polars DataFrames and
+  Arrow tables. Without a connection, `Model.from_tables` registers them in a
+  private in-process DuckDB under their mapping names; nothing is uploaded.
+  These models materialize only. Durable staging, reopening and refresh need
+  a file-backed DuckDB; refusals provide that route.
+  DataFrame detection accepts classes exposed from the public package module
+  as well as submodules, including pandas 3.1.
+- `Model.to_catalog()` writes equivalent version-2 YAML for reuse with
+  `Model.from_catalog`.
+- Unit inference applies wherever a Design meets a Model, including validation,
+  preview, build, snapshot, planning, staging and agent tools. Multiple units
+  require an explicit choice; inferred and explicit units share resolved dataset
+  identity.
+- `Schedule`, `time_series` and `trial_panel` accept `"1mo"`, `"3mo"` and
+  `"1y"` calendar steps. Anchors advance from the original start and clamp to
+  month-end without cumulative drift. `count`, `instant` and `instants` expose
+  this arithmetic. Windows and other elapsed fields still require seconds,
+  minutes, hours, days or weeks; state and calendar-comparison panels require
+  a fixed elapsed cadence.
+  Normalized calendar steps must fit in 19 decimal digits, so accepted year
+  steps remain readable from their serialized month representation.
+- `Frame.to_pandas(values_only=True)` and `to_polars(values_only=True)` retain
+  identity, role and structural value columns while dropping completeness,
+  reason and bookkeeping columns. Incomplete values remain null.
+  `training_set(...).to_pandas(values_only=True)` yields the in-memory feature
+  and label table. Observation metadata cannot be requested with this flag;
+  Arrow conversions remain lossless.
+- `Design.describe(model)` validates and summarizes rows, anchors, expressions,
+  shape, treatment, completeness and output columns without querying source
+  rows. Agent design validation/proposal responses include the same summary.
+- Unknown-name refusals include sorted `available` declarations, including
+  `model.metrics` for unknown metrics. Refusal messages identify the user's
+  input and a route forward; temporal errors identify the output and offending
+  bounds. New codes are `terrine.model.ambiguous_unit`,
+  `terrine.dataset.invalid_split`, `terrine.budget.invalid_limit`,
+  `terrine.runtime.invalid_configuration`, `terrine.export.invalid_input` and
+  `terrine.simulate.invalid_config`.
+- Public constructors, recipes and conversion methods include concise
+  docstrings ending in an executable one-line example.
+- Warehouse exports retain scoring rows when there are no outcome windows.
+
+### Documentation
+
+- The README builds a customer spend forecasting table directly from DataFrames,
+  with user-named metrics, inclusive monthly snapshots, `describe` and executed
+  printed output; in-memory materialization and file-backed staging are distinct.
+- The library hand-off guide builds a catalog-backed treatment/outcome grid of
+  trial panels for DoubleML, preserving repeated-unit clusters and distinct
+  nullable event labels; DoWhy's one-row-per-unit and weight restrictions remain
+  explicit. Terrine makes no causal claims.
+- Guides cover `History`, metric constructors, catalog export, unit inference,
+  inclusive date bounds, calendar schedules, values-only views, training sets
+  and coded refusals.
+
+### Tests
+
+- Catalog/design round trips, date-bound and calendar arithmetic oracles,
+  DataFrame/timezone parity, metric/filter/history contracts, inferred-unit
+  identity, values-only columns, metadata-only summaries, coded constructor
+  refusals and public docstring examples cover the API.
+- Acceptance tests execute the README and file-backed staging tutorial and all
+  four causal-grid pairs, check distinct treated populations and outcome values,
+  and construct clustered `DoubleMLData` when the extra is installed.
+- Refresh unit and integration duration records for balanced CI groups.
+
 ## 0.1.0.dev1
 
 ### Backend compatibility

{terrine-0.1.0.dev1 → terrine-0.1.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: terrine
-Version: 0.1.0.dev1
+Version: 0.1.0.dev2
 Summary: Typed dataset construction and analytical workflows
 Project-URL: Homepage, https://github.com/kylejcaron/terrine
 Project-URL: Documentation, https://github.com/kylejcaron/terrine/tree/main/docs/guides
@@ -57,6 +57,9 @@ Description-Content-Type: text/markdown
 
 # terrine
 
+> [!WARNING]
+> Terrine is an experimental idea for simplifying dataset curation. It is pre-alpha: the API will change without notice, and it is not ready for production use.
+
 **Build datasets directly from event logs.**
 
 You have event tables: orders, sessions, payments. You want a modeling table, for example one row per customer per snapshot date, with features computed from the past and labels from the future. Terrine builds that table in your warehouse (DuckDB, PostgreSQL, BigQuery, Snowflake, and more) from a few lines of Python.
@@ -84,7 +87,6 @@ pip install --pre "terrine[duckdb,pandas]"
 
 <!-- --8<-- [start:first-dataset] -->
 ```python
-import ibis
 import pandas as pd
 import terrine as tr
 
@@ -97,32 +99,28 @@ orders = pd.DataFrame({
     "amount": [30.0, 45.0, 25.0, 60.0, 80.0],
 })
 
-con = ibis.duckdb.connect()  # or your warehouse: ibis.bigquery.connect(...), ...
-con.create_table("customers", customers)
-con.create_table("orders", orders)
-
-# Tell Terrine who the rows are about and which dates the orders table covers.
+# Who the rows are about, which table holds the events, what to measure,
+# and which calendar days (inclusive) the orders table is fully loaded for.
 model = tr.Model.from_tables(
-    con,
-    units={"customer": tr.UnitSource("customers", "customer_id")},
+    units={"customer": tr.UnitSource(customers, "customer_id")},
     events={"orders": tr.Events(
-        "orders", "ordered_at", {"customer": "customer_id"},
-        values=("amount",), complete=("2025-01-01", "2025-03-20"),
+        orders, time="ordered_at", key="customer_id",
+        metrics={"orders": tr.count(), "spend": tr.sum("amount")},
+        complete=("2025-01-01", "2025-03-20"),
     )},
 )
 
-# One row per customer every 28 days: the last 30 days as features,
-# spend in the next 30 days as the target.
+# One row per customer on the first of each month, February through March:
+# the last 30 days as features, spend in the next 30 days as the target.
 design = tr.recipes.time_series(
-    "customer", every="28d", start="2025-02-01", end="2025-03-02",
+    every="1mo", start="2025-02-01", end="2025-03-01",
     features={
-        "orders_30d": tr.agg("orders_count", window=("-30d", "0s")),
-        "spend_30d": tr.agg("orders_amount_sum", window=("-30d", "0s")),
-    },
-    outcomes={
-        "spend_next_30d": tr.agg("orders_amount_sum", window=("0s", "30d")),
+        "orders_30d": tr.agg("orders", window=("-30d", "0s")),
+        "spend_30d": tr.agg("spend", window=("-30d", "0s")),
     },
+    outcomes={"spend_next_30d": tr.agg("spend", window=("0s", "30d"))},
 )
+print(design.describe(model))
 
 data = design.build(model).to_pandas()
 columns = ["unit", "t0", "orders_30d", "spend_30d", "spend_next_30d", "spend_next_30d__reason"]
@@ -130,7 +128,29 @@ print(data[columns].assign(t0=data["t0"].dt.date).sort_values(["t0", "unit"]).to
 ```
 <!-- --8<-- [end:first-dataset] -->
 
+`describe` explains the rows, windows and declared completeness without querying
+the source tables ([sample summary](https://github.com/kylejcaron/terrine/blob/main/docs/guides/design-validation.md#describing-a-design)).
+Running the example prints:
+
 ```text
+One row per customer (table customer, key customer_id) at each snapshot.
+Snapshots: every 1 month from 2025-02-01 through 2025-03-01 (2 dates: 2025-02-01, 2025-03-01), at
+  00:00 UTC.
+Features (before t0):
+  orders_30d: count of orders in [t0 - 30d, t0)
+  spend_30d: sum of orders.amount in [t0 - 30d, t0)
+Outcomes (after t0):
+  spend_next_30d: sum of orders.amount in [t0, t0 + 30d)
+Completeness: orders is declared complete for 2025-01-01 through 2025-03-20 (UTC days).
+  A metric window outside declared source coverage is null with reason incomplete_coverage; unit
+    observation bounds use incomplete_observation.
+Empty complete metric windows (no matching events):
+  orders_30d: 0 (no reason)
+  spend_30d: 0 (no reason)
+  spend_next_30d: 0 (no reason)
+Columns: unit, anchor_id, t0, orders_30d, orders_30d__complete, orders_30d__reason, spend_30d,
+  spend_30d__complete, spend_30d__reason, spend_next_30d, spend_next_30d__complete,
+  spend_next_30d__reason.
  unit         t0  orders_30d  spend_30d  spend_next_30d spend_next_30d__reason
 alice 2025-02-01           2       75.0            25.0                   <NA>
   bob 2025-02-01           1       80.0             0.0                   <NA>
@@ -148,15 +168,15 @@ Reading the output:
 - **Alice's February 10 order** is in her February 1 target and her March 1 features. The same order is the future for one row and the past for the next.
 - **The March targets are unknown.** Their 30-day window runs past March 20, where the orders data ends. Drop them, keep them for scoring, or handle them however suits your model.
 
-Terrine names metrics after your table and columns: `orders_count`, `orders_amount_sum` and `orders_amount_mean`. Every value has a `<name>__complete` flag and a `<name>__reason` column, so you can filter or impute deliberately.
+You name the metrics: `tr.count()` counts events, `tr.sum("amount")` adds a column, and `tr.count(where={"status": "refunded"})` counts only matching events once `status` is declared in `labels=`. Every value has a `<name>__complete` flag and a `<name>__reason` column, so you can filter or impute deliberately.
 
 ## The four ideas
 
 | Idea | In the example |
 | --- | --- |
 | **Unit:** who each row is about, read from a table so nobody silently drops out | `customers.customer_id` |
-| **t0:** the snapshot time of each row | every 28 days from 2025-02-01 |
-| **Windows:** relative to t0, start included, end excluded. Features must end at or before t0; outcomes must start at or after t0 | `("-30d", "0s")` is the 30 days before t0; `("0s", "30d")` is the 30 days after |
+| **t0:** the snapshot time of each row. `every` is an elapsed duration (`"7d"`, `"4w"`) or a calendar step (`"1mo"`, `"3mo"`, `"1y"`); a monthly schedule from the 31st lands on Jan 31, Feb 28, Mar 31 | `every="1mo"`: the first of each month from 2025-02-01 through 2025-03-01, both days included |
+| **Windows:** relative to t0, start included, end excluded. Features must end at or before t0; outcomes must start at or after t0. Windows are elapsed time: `"-1mo"` is refused, use `"-30d"` or `"-4w"` | `("-30d", "0s")` is the 30 days before t0; `("0s", "30d")` is the 30 days after |
 | **Completeness:** the calendar days, inclusive, that you declare fully loaded for each event table (not just the first and last event you happen to have). Windows outside them are unknown, not zero | `complete=("2025-01-01", "2025-03-20")` |
 
 ## Other datasets
@@ -177,7 +197,7 @@ More feature recipes are in [common feature patterns](https://github.com/kylejca
 
 ## Where it runs
 
-Queries run where your data lives; nothing is uploaded. Results come back as pandas, Polars or Arrow.
+Queries run where your data lives; nothing is uploaded. DataFrames and Arrow tables, as above, are queried in a private in-process DuckDB. For a warehouse, pass its Ibis connection first and name the tables: `tr.Model.from_tables(con, units={"customer": tr.UnitSource("customers", "customer_id")}, events={"orders": tr.Events("orders", ...)})`. Results come back as pandas, Polars or Arrow.
 
 | Backend | Status |
 | --- | --- |

{terrine-0.1.0.dev1 → terrine-0.1.0.dev2}/README.md

@@ -1,5 +1,8 @@
 # terrine
 
+> [!WARNING]
+> Terrine is an experimental idea for simplifying dataset curation. It is pre-alpha: the API will change without notice, and it is not ready for production use.
+
 **Build datasets directly from event logs.**
 
 You have event tables: orders, sessions, payments. You want a modeling table, for example one row per customer per snapshot date, with features computed from the past and labels from the future. Terrine builds that table in your warehouse (DuckDB, PostgreSQL, BigQuery, Snowflake, and more) from a few lines of Python.
@@ -27,7 +30,6 @@ pip install --pre "terrine[duckdb,pandas]"
 
 <!-- --8<-- [start:first-dataset] -->
 ```python
-import ibis
 import pandas as pd
 import terrine as tr
 
@@ -40,32 +42,28 @@ orders = pd.DataFrame({
     "amount": [30.0, 45.0, 25.0, 60.0, 80.0],
 })
 
-con = ibis.duckdb.connect()  # or your warehouse: ibis.bigquery.connect(...), ...
-con.create_table("customers", customers)
-con.create_table("orders", orders)
-
-# Tell Terrine who the rows are about and which dates the orders table covers.
+# Who the rows are about, which table holds the events, what to measure,
+# and which calendar days (inclusive) the orders table is fully loaded for.
 model = tr.Model.from_tables(
-    con,
-    units={"customer": tr.UnitSource("customers", "customer_id")},
+    units={"customer": tr.UnitSource(customers, "customer_id")},
     events={"orders": tr.Events(
-        "orders", "ordered_at", {"customer": "customer_id"},
-        values=("amount",), complete=("2025-01-01", "2025-03-20"),
+        orders, time="ordered_at", key="customer_id",
+        metrics={"orders": tr.count(), "spend": tr.sum("amount")},
+        complete=("2025-01-01", "2025-03-20"),
     )},
 )
 
-# One row per customer every 28 days: the last 30 days as features,
-# spend in the next 30 days as the target.
+# One row per customer on the first of each month, February through March:
+# the last 30 days as features, spend in the next 30 days as the target.
 design = tr.recipes.time_series(
-    "customer", every="28d", start="2025-02-01", end="2025-03-02",
+    every="1mo", start="2025-02-01", end="2025-03-01",
     features={
-        "orders_30d": tr.agg("orders_count", window=("-30d", "0s")),
-        "spend_30d": tr.agg("orders_amount_sum", window=("-30d", "0s")),
-    },
-    outcomes={
-        "spend_next_30d": tr.agg("orders_amount_sum", window=("0s", "30d")),
+        "orders_30d": tr.agg("orders", window=("-30d", "0s")),
+        "spend_30d": tr.agg("spend", window=("-30d", "0s")),
     },
+    outcomes={"spend_next_30d": tr.agg("spend", window=("0s", "30d"))},
 )
+print(design.describe(model))
 
 data = design.build(model).to_pandas()
 columns = ["unit", "t0", "orders_30d", "spend_30d", "spend_next_30d", "spend_next_30d__reason"]
@@ -73,7 +71,29 @@ print(data[columns].assign(t0=data["t0"].dt.date).sort_values(["t0", "unit"]).to
 ```
 <!-- --8<-- [end:first-dataset] -->
 
+`describe` explains the rows, windows and declared completeness without querying
+the source tables ([sample summary](https://github.com/kylejcaron/terrine/blob/main/docs/guides/design-validation.md#describing-a-design)).
+Running the example prints:
+
 ```text
+One row per customer (table customer, key customer_id) at each snapshot.
+Snapshots: every 1 month from 2025-02-01 through 2025-03-01 (2 dates: 2025-02-01, 2025-03-01), at
+  00:00 UTC.
+Features (before t0):
+  orders_30d: count of orders in [t0 - 30d, t0)
+  spend_30d: sum of orders.amount in [t0 - 30d, t0)
+Outcomes (after t0):
+  spend_next_30d: sum of orders.amount in [t0, t0 + 30d)
+Completeness: orders is declared complete for 2025-01-01 through 2025-03-20 (UTC days).
+  A metric window outside declared source coverage is null with reason incomplete_coverage; unit
+    observation bounds use incomplete_observation.
+Empty complete metric windows (no matching events):
+  orders_30d: 0 (no reason)
+  spend_30d: 0 (no reason)
+  spend_next_30d: 0 (no reason)
+Columns: unit, anchor_id, t0, orders_30d, orders_30d__complete, orders_30d__reason, spend_30d,
+  spend_30d__complete, spend_30d__reason, spend_next_30d, spend_next_30d__complete,
+  spend_next_30d__reason.
  unit         t0  orders_30d  spend_30d  spend_next_30d spend_next_30d__reason
 alice 2025-02-01           2       75.0            25.0                   <NA>
   bob 2025-02-01           1       80.0             0.0                   <NA>
@@ -91,15 +111,15 @@ Reading the output:
 - **Alice's February 10 order** is in her February 1 target and her March 1 features. The same order is the future for one row and the past for the next.
 - **The March targets are unknown.** Their 30-day window runs past March 20, where the orders data ends. Drop them, keep them for scoring, or handle them however suits your model.
 
-Terrine names metrics after your table and columns: `orders_count`, `orders_amount_sum` and `orders_amount_mean`. Every value has a `<name>__complete` flag and a `<name>__reason` column, so you can filter or impute deliberately.
+You name the metrics: `tr.count()` counts events, `tr.sum("amount")` adds a column, and `tr.count(where={"status": "refunded"})` counts only matching events once `status` is declared in `labels=`. Every value has a `<name>__complete` flag and a `<name>__reason` column, so you can filter or impute deliberately.
 
 ## The four ideas
 
 | Idea | In the example |
 | --- | --- |
 | **Unit:** who each row is about, read from a table so nobody silently drops out | `customers.customer_id` |
-| **t0:** the snapshot time of each row | every 28 days from 2025-02-01 |
-| **Windows:** relative to t0, start included, end excluded. Features must end at or before t0; outcomes must start at or after t0 | `("-30d", "0s")` is the 30 days before t0; `("0s", "30d")` is the 30 days after |
+| **t0:** the snapshot time of each row. `every` is an elapsed duration (`"7d"`, `"4w"`) or a calendar step (`"1mo"`, `"3mo"`, `"1y"`); a monthly schedule from the 31st lands on Jan 31, Feb 28, Mar 31 | `every="1mo"`: the first of each month from 2025-02-01 through 2025-03-01, both days included |
+| **Windows:** relative to t0, start included, end excluded. Features must end at or before t0; outcomes must start at or after t0. Windows are elapsed time: `"-1mo"` is refused, use `"-30d"` or `"-4w"` | `("-30d", "0s")` is the 30 days before t0; `("0s", "30d")` is the 30 days after |
 | **Completeness:** the calendar days, inclusive, that you declare fully loaded for each event table (not just the first and last event you happen to have). Windows outside them are unknown, not zero | `complete=("2025-01-01", "2025-03-20")` |
 
 ## Other datasets
@@ -120,7 +140,7 @@ More feature recipes are in [common feature patterns](https://github.com/kylejca
 
 ## Where it runs
 
-Queries run where your data lives; nothing is uploaded. Results come back as pandas, Polars or Arrow.
+Queries run where your data lives; nothing is uploaded. DataFrames and Arrow tables, as above, are queried in a private in-process DuckDB. For a warehouse, pass its Ibis connection first and name the tables: `tr.Model.from_tables(con, units={"customer": tr.UnitSource("customers", "customer_id")}, events={"orders": tr.Events("orders", ...)})`. Results come back as pandas, Polars or Arrow.
 
 | Backend | Status |
 | --- | --- |

{terrine-0.1.0.dev1 → terrine-0.1.0.dev2}/benchmarks/run_overhead.py

@@ -79,20 +79,20 @@ WORKLOADS: tuple[Workload, ...] = (
 def _catalog() -> Catalog:
     return Catalog.model_validate(
         {
-            "schema_version": 1,
+            "schema_version": 2,
             "day_boundary": "UTC",
             "dialect": "duckdb",
             "sources": {
                 "purchases": {
                     "relation": {"kind": "table", "name": "events"},
-                    "timestamp": "occurred_at",
-                    "entities": {"user": "user_id"},
-                    "facts": ["purchase", "amount", "price"],
+                    "time": "occurred_at",
+                    "units": {"user": "user_id"},
+                    "events": ["purchase", "amount", "price"],
                     "properties": [],
                     "dimensions": [],
                 }
             },
-            "facts": {
+            "events": {
                 "purchase": {"source": "purchases", "column": None},
                 "amount": {"source": "purchases", "column": "amount"},
                 "price": {"source": "purchases", "column": "price"},
@@ -100,17 +100,17 @@ def _catalog() -> Catalog:
             "properties": {},
             "dimensions": {},
             "measures": {
-                "purchase_count": {"fact": "purchase", "aggregation": "count"},
-                "amount_total": {"fact": "amount", "aggregation": "sum"},
-                "price_avg": {"fact": "price", "aggregation": "avg_event"},
+                "purchase_count": {"event": "purchase", "aggregation": "count"},
+                "amount_total": {"event": "amount", "aggregation": "sum"},
+                "price_avg": {"event": "price", "aggregation": "avg_event"},
             },
             "metrics": {
-                "purchases": {"kind": "mean", "entity": "user", "measure": "purchase_count"},
-                "spend": {"kind": "mean", "entity": "user", "measure": "amount_total"},
-                "avg_price": {"kind": "mean", "entity": "user", "measure": "price_avg"},
+                "purchases": {"kind": "mean", "unit": "user", "measure": "purchase_count"},
+                "spend": {"kind": "mean", "unit": "user", "measure": "amount_total"},
+                "avg_price": {"kind": "mean", "unit": "user", "measure": "price_avg"},
                 "spend_per_purchase": {
                     "kind": "ratio",
-                    "entity": "user",
+                    "unit": "user",
                     "numerator": "amount_total",
                     "denominator": "purchase_count",
                 },

{terrine-0.1.0.dev1 → terrine-0.1.0.dev2}/benchmarks/workloads.py

@@ -48,20 +48,20 @@ def _catalog(dialect: str) -> Catalog:
     }
     return Catalog.model_validate(
         {
-            "schema_version": 1,
+            "schema_version": 2,
             "day_boundary": "UTC",
             "dialect": dialect,
             "sources": {
                 "events": {
                     "relation": {"kind": "table", "name": "events"},
-                    "timestamp": "event_time",
-                    "entities": {"user": "unit_id"},
-                    "facts": ["value", "event"],
+                    "time": "event_time",
+                    "units": {"user": "unit_id"},
+                    "events": ["value", "event"],
                     "properties": ["adopted", "event_name"],
                     "dimensions": [],
                 }
             },
-            "facts": {
+            "events": {
                 "value": {"source": "events", "column": "value"},
                 "event": {"source": "events", "column": None},
             },
@@ -76,11 +76,11 @@ def _catalog(dialect: str) -> Catalog:
             },
             "dimensions": {},
             "measures": {
-                name: {"fact": "value", "aggregation": aggregation}
+                name: {"event": "value", "aggregation": aggregation}
                 for name, aggregation in aggregations.items()
             },
             "metrics": {
-                name: {"kind": "mean", "entity": "user", "measure": measure}
+                name: {"kind": "mean", "unit": "user", "measure": measure}
                 for name, measure in (*((name, name) for name in aggregations), ("value", "total"))
             },
         }
@@ -137,7 +137,7 @@ def designs(config: ScaleConfig) -> dict[str, Design]:
         Schedule(
             "1d",
             (_EPOCH + timedelta(days=config.window_days)).date(),
-            (_EPOCH + timedelta(days=config.window_days + config.anchor_periods)).date(),
+            (_EPOCH + timedelta(days=config.window_days + config.anchor_periods - 1)).date(),
         ),
         features=features,
     )

{terrine-0.1.0.dev1 → terrine-0.1.0.dev2}/docs/guides/backend-compatibility.md

@@ -205,7 +205,7 @@ precision and refuses rather than narrows.
   magnitude sum (`γₖ = k · u / (1 − k · u)`), so a partition is admitted iff
   `B < limit · (1 − e)`. Otherwise its values are withheld before the backend
   adds them and every consumer of that state refuses: sums, averages and
-  ratios with `float64_precision` (`bound_overflow`) for float facts or
+  ratios with `float64_precision` (`bound_overflow`) for float event values or
   `terrine.temporal.exact_overflow` for coefficients, cohort totals and means
   and cumulative trajectories with their existing overflow reasons. This
   bound is deliberately conservative: opposite-sign history whose magnitudes

{terrine-0.1.0.dev1 → terrine-0.1.0.dev2}/docs/guides/candidate-anchors.md

@@ -2,16 +2,17 @@
 
 Use `design.build(model)` to compile a lazy Frame; materialization and staging run the required integrity checks through the owned execution path. Its candidate rows retain `unit`, `anchor_id`, exact `t0`, observation bounds and anchor provenance. Building does not execute source-data queries. Anchor integrity refusals expose stable `check_key` values such as `null_roster_key`, `duplicate_roster_key`, `null_event_id`, `duplicate_event_id`, `null_event_unit`, `null_event_timestamp`, `tied_event_timestamps` and `ambiguous_event_identity`. Correct the named source contract instead of silently deduplicating candidates.
 
-`FixedDate` and `Schedule` use the explicitly declared `UnitSource` roster for the design's logical unit. Roster entry/exit bounds are membership bounds evaluated as `[entered_at, exited_at)` at each candidate `t0`. Observation bounds are copied independently; a missing bound remains null and roster exit is not used as censoring. Fixed-date calendar bounds resolve through the Catalog's declared day boundary. Schedules advance by elapsed seconds from start and exclude their end.
+`FixedDate` and `Schedule` use the explicitly declared `UnitSource` roster for the design's logical unit. Roster entry/exit bounds are membership bounds evaluated as `[entered_at, exited_at)` at each candidate `t0`. Observation bounds are copied independently; a missing bound remains null and roster exit is not used as censoring. Fixed-date calendar bounds resolve through the Catalog's declared day boundary. Schedules advance by elapsed seconds from the start day through the end day, which is included: the anchors are every `t0 = day(start) + k * every` before `day(end + 1 day)`.
 
-`EventAnchor` reads the declared fact's bound source and physical entity mapping. Fact values are not used as event-presence predicates: a row is an event even when its fact column is null. The source's `Model.event_ids` column is retained from raw relation rows for stable tie ordering and identity. Aware timestamp components of fallback or configured event identities are rendered after explicit UTC normalization, independent of the session timezone. `first` and `nth` are selected over full source history before `Design.anchor_range` filtering; `each` retains every event. A range is half-open; calendar-date endpoints resolve through Catalog day-boundary semantics and aware datetime endpoints remain exact UTC instants.
+`EventAnchor` reads the named event's bound source and physical unit mapping. Event values are not used as event-presence predicates: a row is an event even when its event column is null. The source's `Model.event_ids` column is retained from raw relation rows for stable tie ordering and identity. Aware timestamp components of fallback or configured event identities are rendered after explicit UTC normalization, independent of the session timezone. `first` and `nth` are selected over full source history before `Design.anchor_range` filtering; `each` retains every event. A range starts at its `start` bound; a calendar-date `end` keeps the whole of that local day, resolved through Catalog day-boundary semantics, while an aware datetime `end` remains an exact exclusive UTC instant.
 
 ## Landmark event anchors
 
 `EventAnchor("purchase", offset="1d")` sets `t0` to the selected purchase
 instant plus one elapsed day. Offsets default to zero and accept non-negative
 integral seconds or `s`/`m`/`h`/`d`/`w` durations. Negative offsets refuse at
-construction with `terrine.design.invalid`. Selection and `anchor_range` use
+construction with `terrine.design.invalid` (`reason="negative"`,
+`field="offset"`). Selection and `anchor_range` use
 the **original event time**, not the landmark; the shift happens afterward.
 Roster membership and all feature/outcome windows use the resulting `t0`.
 
@@ -43,7 +44,7 @@ Frame materialization or a full rebuild instead.
 ## Source integrity
 
 
-An event anchor must name a fact declared by its bound source, not merely
+An event anchor must name an event declared by its bound source, not merely
 present elsewhere in the Catalog; missing references use the same refusal
 as `Design.validate`. Unrelated source columns cannot change generated
 identities, including columns whose names differ only by case from a