terrine 0.1.0.dev0__tar.gz → 0.1.0.dev1__tar.gz

{terrine-0.1.0.dev0 → terrine-0.1.0.dev1}/.github/workflows/ci.yml

@@ -72,6 +72,10 @@ jobs:
           --splits 6 --group ${{ matrix.group }}
           --splitting-algorithm least_duration
           --durations-path integration/.test_durations
+      # The same known answers compiled through the portable base expression
+      # policy; about twenty seconds beside the native run.
+      - if: matrix.group == 1
+        run: uv run pytest -q integration/conformance --generic-dialect
   docs-and-examples:
     runs-on: ubuntu-latest
     timeout-minutes: 30

{terrine-0.1.0.dev0 → terrine-0.1.0.dev1}/.gitignore

@@ -14,6 +14,7 @@ dist/
 build/
 *.egg-info/
 .superpowers/
+docs/superpowers/
 .worktrees/
 
 # Local mutation campaigns

{terrine-0.1.0.dev0 → terrine-0.1.0.dev1}/AGENTS.md

@@ -94,12 +94,30 @@ Reached schedules and deadlines use notify.* for the current owner, or the autho
   random sample without replacement; the default executes every mutant.
   Campaigns are local only, not part of ordinary checks or CI.
 - `make test-postgres` runs the live PostgreSQL probes (`@pytest.mark.postgres`,
-  deselected by default); they fail, never skip, without
+  deselected by default) and then the conformance known answers with the
+  portable base expression policy forced; they fail, never skip, without
   `TERRINE_TEST_POSTGRES_*` settings. Start a throwaway local server with
   `eval "$(uv run python -m tests.integration.postgres_scratch start)"` and stop it
   with `uv run python -m tests.integration.postgres_scratch stop`. CI runs them
   on every push against a PostgreSQL 16 service container. Each probe owns a
   uniquely named schema; never share a warehouse namespace between tests.
+- `uv run pytest integration/conformance` runs known answers on DuckDB by default,
+  with parameters derived from the verified engine registry. Select the same cases
+  on a configured scratch warehouse with
+  `uv run --extra <engine> pytest integration/conformance -m <engine>` for
+  `postgres`, `bigquery` or `snowflake`; they are also included in the matching
+  `make test-<engine>` target. The module's connection-fixture table must cover
+  every registered engine. Add `--generic-dialect` to compile the same known
+  answers with the portable base expression policy on each real connection
+  (`uv run pytest integration/conformance --generic-dialect`; with
+  `--extra postgres ... -m postgres` on the scratch server). The forced run
+  takes about twenty seconds per backend and is part of the integration and
+  PostgreSQL checks on every push; the portable policy's own numerical and
+  relational oracles live in `integration/backends/test_generic.py` and force
+  it unconditionally, and its real unregistered-backend reads on Ibis SQLite
+  live in `integration/execution/test_generic_provider.py`. Test module
+  basenames under `integration/` must be unique: the tree has no packages, so
+  two `test_x.py` files cannot both be collected.
 - `make test-bigquery` runs the live BigQuery probes (`@pytest.mark.bigquery`,
   deselected by default); they fail, never skip, without
   `TERRINE_TEST_BIGQUERY_PROJECT`, `TERRINE_TEST_BIGQUERY_DATASET` and
@@ -242,16 +260,47 @@ Reached schedules and deadlines use notify.* for the current owner, or the autho
   raw SQL strings or `@ibis.udf.*.builtin` bindings to native functions there;
   ruff (`TID251`) rejects `ibis.udf` and `ibis.to_sql` outside the allowed
   packages.
-- When Ibis lacks or mistranslates an operation on a supported backend, add a
-  dispatched helper in `terrine/backends/` (`dialect`, `numeric`, `timestamps`,
-  `joins`, `extrema`) with a live parity test, not a workaround at each call
-  site. Supporting a new warehouse means implementing those helpers for it.
-  Known Ibis gaps: no ASOF JOIN on BigQuery, NULL-propagating LEAST/GREATEST
-  there, and `interval * column` lowered through `EXTRACT(SECOND ...)` (multiply
-  integer seconds, then `.as_interval("s")`).
+- When Ibis lacks or mistranslates an operation on a supported backend, implement
+  the override in that engine's `terrine/backends/engines/<name>.py` dialect,
+  with a live parity test, not a workaround at each call site. Shared helpers
+  (`numeric`, `timestamps`, `joins`, `extrema`, `sequences`) delegate engine
+  differences to the selected dialect. Native function bindings belong in
+  concrete engine modules. Known Ibis gaps: no ASOF JOIN on BigQuery,
+  NULL-propagating LEAST/GREATEST there, and `interval * column` lowered through
+  `EXTRACT(SECOND ...)` (multiply integer seconds, then `.as_interval("s")`).
 - Raw SQL is acceptable only for: terrine's own DuckDB runtime state tables
   (`terrine/runtime/`), backend-provider catalog introspection and transaction
-  control (`terrine/execution/`), and admitted user SQL relations.
+  control (`terrine/execution/`), admitted user SQL relations, and the existing
+  qualified read-only PostgreSQL identity callback in `terrine/backends/engines/`.
+- `terrine/backends/registry.py` owns verified engine names, capability values,
+  feature boundaries and lazy dialect, identity and execution-provider paths.
+  Add an engine through that registry and one concrete dialect override module,
+  with admission evidence; do not introduce supported-engine lists in consumers.
+  Capability inspection is metadata-only and never runs querying identity admission.
+  `tests/test_engine_dispatch.py` rejects engine-name selection outside those
+  modules; it is a heuristic review aid, not proof of centralized dispatch.
+- Backends have three tiers. Verified engines are the `ENGINES` registrations
+  with native dialect overrides and consistent-view providers. Any other
+  genuine Ibis backend is unverified: it refuses by default and, only after a
+  Model's `allow_unverified=True`, runs read-only statement-scoped reads under
+  the separate `GENERIC` record, whose expression policy is the unmodified
+  base `Dialect` in `terrine/backends/dialect.py` and whose provider is
+  `terrine/execution/_generic.py`. Raw drivers, name-only objects and failed
+  registered identities stay refused with or without the flag, as do every
+  effect (staging, retained capture, publication, reopening) on an unverified
+  backend. Extend the portable tier by completing the base `Dialect` method
+  or adding an operation-specific coded refusal there, never by naming a
+  backend; a base default must not advertise an operation a registered
+  engine's `operations` declaration excludes, so add the engine override that
+  keeps its refusal. The portable policy answers exactly or refuses by code:
+  lazy scalar known-answer witnesses (exact decimals, UTC wall clocks across
+  daylight saving) run once per execution context before source rows are
+  read, and accumulations are withheld by a derived magnitude bound rather
+  than trusted to the backend.
+- The PostgreSQL engine's identity callback owns the existing qualified,
+  read-only `SELECT pg_catalog.version()` admission exception. It checks the
+  Ibis floor before reading identity and refuses before source metadata access;
+  expression policies otherwise issue no connection probes.
 - Warehouse results match the DuckDB reference within a stated tolerance
   (floats: tight, relative to the window's absolute sum, since cancellation
   defeats a purely relative bound; exact for counts and decimal sums).

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

@@ -1,6 +1,200 @@
 # Changelog
 
-## Unreleased
+## 0.1.0.dev1
+
+### Backend compatibility
+
+- Admit any other genuine Ibis backend for read-only use only after an
+  explicit `allow_unverified=True` on `Model.from_catalog`, `Model.from_tables`
+  or `Model.from_increment`. By default such a backend refuses with
+  `terrine.backend.capability_unavailable` (`operation="query"`,
+  `status="unverified"`, a route naming the flag and the verified engines)
+  before its schema is read; a non-Boolean choice refuses with
+  `terrine.model.invalid_binding`. Admission emits the new filterable
+  `terrine.UnverifiedBackendWarning` once at the caller's line and binds
+  consent to that Model, not the connection. Registered identity failures,
+  raw drivers and name-only connections remain refused with or without the
+  flag. The separate `GENERIC` engine record is read-only: retained input
+  capture, staging, publication, published Dataset reopening, native Parquet
+  unload and transaction snapshots refuse before any write, and strict scan
+  budgets still refuse unknown source costs. `Catalog.dialect` keeps the
+  connection's real SQL dialect; the expression policy is `generic`.
+- Execute admitted reads on the caller's borrowed connection, one independent
+  statement at a time: Terrine issues no transaction control, session
+  settings, temporary objects, cloning or disconnection, but Ibis schema
+  inspection may end an open caller transaction, so pass a connection with no
+  pending writes or a dedicated read connection. The execution snapshot has
+  no identity and `replay_equivalence="unverified"`. Admitted SQL and every
+  compiled statement are parsed for read-only safety in the real dialect and
+  fail closed with `terrine.sql.invalid_read_query`. Every SQL verification
+  step on every engine (parsing, rendering, scope analysis, the PostgreSQL
+  function check, the BigQuery and Snowflake routine checks and Snowflake's
+  Time Travel pinning) runs on a fresh thread, whose recursion depth is
+  counted separately, so a deeply nested compiled statement is verified
+  whatever the caller's own stack depth without changing the interpreter's
+  recursion limit, and relation discovery reads the verified scope graph
+  rather than traversing nested derived tables again; a statement too deep to
+  verify even then refuses with `terrine.sql.invalid_read_query` and
+  `reason="too_deep_to_verify"`, never as unsafe SQL or a raw
+  `RecursionError`. Unsupported primitives
+  refuse with `capability_unavailable` naming the backend and operation,
+  chained from the backend's exception; owned Arrow readers are released on
+  exhaustion, error, early close or context closure, and a failure during
+  batch consumption carries the same code.
+- Run lazy scalar known-answer witnesses once per execution context, before
+  any source row and only when a relation needs them; materialization and the
+  bounded preview submit every relation they will run (output, audit and each
+  integrity check) as soon as the study is compiled, so an unsupported
+  primitive refuses before its roster and event checks scan, while an
+  independent statement on an execution context is admitted when issued:
+  exact decimal arithmetic
+  (scale-9 low digits at a large offset, cancellation, the domain edges,
+  signed quotients, both `int64` endpoints and a 38-digit coefficient), which
+  refuses `operation="exact_state"` on a backend such as SQLite that stores
+  decimals by affinity, and UTC wall clocks of aware-timestamp deltas at four
+  instants across daylight-saving, pre-epoch and local-mean-time offsets,
+  which refuses `operation="utc_wall_clock"` where Ibis lowers the delta
+  through session wall clocks (PostgreSQL-family backends in a non-UTC
+  session) rather than answering by the session offset. Nanosecond
+  timestamps refuse the portable UTC conversions (`utc_wall_clock`,
+  `utc_instant`) while the expression is built; sub-second parts keep
+  nanosecond support.
+- Complete the portable base expression policy used after unverified
+  admission, so every study expression is an ordinary Ibis expression without
+  native bindings. Float facts enter as `DECIMAL(38, 9)` state by truncating
+  the backend's decimal text toward zero at nine places (`|Q9(t) - t| <
+  10**-9`; magnitudes at or above `10**29` and non-finite values refuse with
+  the existing `float64_precision` failures); counts and source-decimal
+  coefficients stay in a separate `DECIMAL(38, 0)` domain whose literals,
+  typed NULLs and narrowing bounds take the coefficient's type. Prefix
+  differences leaving the fixed domain and outputs leaving their target type
+  refuse with the existing codes. Accumulations are admitted only when a
+  binary64 bound on their magnitudes proves the exact sum fits: with `n`
+  contributing values the computed bound `B` lies within
+  `e = (1 + u)(1 + γ_{n-1}) - 1` of the true magnitude sum (`u = 2**-53`,
+  `γ_k = k·u / (1 - k·u)`), so a partition is admitted iff
+  `B < limit · (1 - e)`, evaluated with its own rounding on the conservative
+  side; otherwise its values are withheld before the backend adds them and
+  every consumer of the state (sums, averages, ratios, cohort totals and
+  means, cumulative trajectories) refuses with `float64_precision`
+  (`bound_overflow`) for float facts or `exact_overflow` for coefficients,
+  never a backend error, a narrowed value or a silent NULL. The bound is
+  deliberately conservative: opposite-sign history whose magnitudes alone
+  exceed the domain is refused even where the exact difference would fit.
+  Exact-state ratios divide correctly rounded binary64 operands once (within
+  `3.1u` before later rounding); integer quotients truncate toward zero
+  through a certified decimal residual correction and are NULL beyond int64
+  or for a zero divisor. Timestamps use native order, typed UTC epoch deltas
+  and signed parts; fixed-offset local days and their start instants derive
+  from one epoch delta and one floor quotient (`Dialect.local_day`,
+  `Dialect.day_start`) with every intermediate inside `int64` at both
+  endpoints under the extreme offsets, which keeps day buckets and endpoint
+  alignment shallow where chained conversions would nest (registered engines
+  keep their cast-based forms, compiled unchanged); the union/window as-of
+  fallback, coalesced extrema and portable integer sequences are the
+  defaults. Measured on DuckDB and
+  PostgreSQL 16 with the policy forced: shortest round-trip float text within
+  half an ulp, exact `0.1 + 0.2` and scale-2 cancellation, both signed
+  `int64` quotient endpoints, and nested quotients within `8u`. Registered
+  engines keep their native state and every previously refused operation
+  (`exact_ratio` and `exact_is_nonfinite` on DuckDB and Snowflake; normalized
+  significand division on PostgreSQL and BigQuery) through explicit
+  overrides; their native conversions, refusals and session lifetimes are
+  unchanged.
+- Record the engine stamp on every result: required `Provenance.engine_name`
+  (actual backend), `dialect` (admitted expression policy) and `engine_status`
+  (its registered status), written by direct materialization, the staged
+  runtime and every fixture builder, and retained through views, cohorts,
+  life tables, Arrow, JSON, manifests and exports. Arrow metadata stays
+  version 2 under `terrine.materialized_frame.v2` and JSON metadata version 1.
+  Payloads saved before the stamp existed decode as their recorded verified
+  execution dialect; a partial stamp, one contradicting the registered policy
+  or the execution snapshot's backend, or an absent stamp with an unregistered
+  execution backend, refuses with the new
+  `terrine.metadata.invalid_engine_stamp` (`reason`, present `fields`) instead
+  of acquiring verified status.
+- Centralize verified engine admission, capability records and expression
+  selection without changing engine execution behavior, supported builds,
+  session lifetimes or connection ownership.
+  Unsupported-operation refusal routes now name registered verified engines
+  implementing the operation, correcting stale DuckDB/PostgreSQL-only advice;
+  exact-ratio routes name PostgreSQL and BigQuery. Refusal codes and non-route
+  context are unchanged.
+  Admission gates and static inspection both honor the selected provider's
+  effective capability evidence; unavailable dialect admission still refuses
+  before materialization.
+- Encapsulate native numeric types, exact arithmetic and float conversion in
+  each engine's expression policy. Shared normalization retains the existing
+  coefficient bounds, NULL/nonfinite flags, overflow behavior and rounding
+  tolerances.
+- Encapsulate timestamp precision, UTC conversion, infinity ordering and exact
+  output narrowing in each engine's expression policy. Explicit timestamp
+  selection also governs nested operations without changing the enclosing
+  expression scope; temporal windows and cohort bucket remainders are unchanged.
+- Centralize as-of joins, NULL-ignoring extrema, integer sequences and feature
+  admission in the registered engine policies. Strict/inclusive cutoffs, duplicate
+  requests, aliases and existing feature/build boundaries are unchanged.
+
+### Fixed
+
+- The registered DuckDB, PostgreSQL and Snowflake UTC conversions treated a
+  naive timestamp as a value to attach UTC to, so the wall clock they returned
+  was zone-aware and any date read from it followed the session time zone: the
+  start of the day containing naive `2025-01-01 00:00:00` came out as
+  `2024-12-31` in an `America/New_York` session. A naive value is its own UTC
+  wall clock and is now returned unchanged, and a UTC-aware value is its own
+  instant. Dataset features were not affected: anchors are UTC-aware and naive
+  source timestamps enter through the instant conversion; the wrong answer was
+  reachable only by applying the wall-clock conversion directly to a naive
+  value, as endpoint alignment on naive values now does.
+- Source distributions no longer include internal planning documents or local
+  build and test output.
+
+### Tests
+
+- Centralize known-answer engine conformance cases for whole-day schedules,
+  NULL-ignoring extrema, cancellation-safe float and exact decimal windows,
+  UTC timestamp conversion, tied event ordering, censor times and strict as-of
+  cutoffs. Run the same cases on DuckDB and live PostgreSQL. Add the day
+  start of a naive timestamp in a non-UTC session, with a day-aligned feature
+  over naive source events.
+- Compile the same known answers with the portable base expression policy on
+  each real connection under `--generic-dialect` (DuckDB by default, PostgreSQL
+  with `-m postgres`), about twenty seconds per backend inside the existing
+  integration and `make test-postgres` checks, and check the policy's
+  numerical and relational contracts against independent oracles on both, plus
+  real unregistered-backend reads and refusals on the Ibis SQLite backend.
+
+### Documentation
+
+- Describe the verified, opted-in unverified and refused backend tiers, the
+  portable numerical contract and its admission witnesses, and the engine
+  stamp in the compatibility, capabilities and public API guides. Add
+  `examples/unverified_backend.py`, which opts in to the Ibis SQLite backend,
+  shows the default refusal, a coded operation refusal, a real read and its
+  stamp.
+- Rewrite the README around a customer spend forecasting table built from
+  pandas DataFrames, with the shapes Terrine builds and how to read its output.
+  The first-dataset guide follows the same example.
+
+### Public API
+
+- `EventAnchor(..., offset="1d")` shifts analysis time zero by a non-negative
+  elapsed duration for landmark datasets, including survival after a baseline
+  feature period. First/nth selection and `anchor_range` retain original-event
+  semantics. Nonzero offsets participate in anchor identity, provenance and
+  Design hashes; zero-offset serialization and hashes remain unchanged.
+  Negative offsets refuse with `terrine.design.invalid`; persisted-layer
+  substitution for shifted anchors refuses before source access with
+  `terrine.compile.runtime_shape_unsupported`. Recipes are unchanged.
+
+### Breaking changes
+
+- Constructing `Provenance` requires `engine_name`, `dialect` and
+  `engine_status`; saved payloads without them still decode as their recorded
+  verified execution dialect.
+
+## 0.1.0.dev0
 
 ### Documentation
 

{terrine-0.1.0.dev0 → terrine-0.1.0.dev1}/Makefile

@@ -27,9 +27,11 @@ test-scale:
 # Live PostgreSQL probes; requires TERRINE_TEST_POSTGRES_* settings and fails
 # without them. `uv run python -m tests.integration.postgres_scratch start` starts
 # a throwaway local server and prints the settings. The extras provide the driver
-# and the DuckDB reference backend.
+# and the DuckDB reference backend. The second run compiles the same conformance
+# known answers through the portable base expression policy on the server.
 test-postgres:
 	uv run --extra duckdb --extra postgres pytest integration -m postgres
+	uv run --extra duckdb --extra postgres pytest integration/conformance --generic-dialect -m postgres
 
 # Live BigQuery probes; requires TERRINE_TEST_BIGQUERY_PROJECT/_DATASET and
 # credentials (GOOGLE_APPLICATION_CREDENTIALS, application-default, or

terrine-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: terrine
+Version: 0.1.0.dev1
+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
+Project-URL: Repository, https://github.com/kylejcaron/terrine
+Project-URL: Changelog, https://github.com/kylejcaron/terrine/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/kylejcaron/terrine/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+License-File: THIRD_PARTY_NOTICES.txt
+Requires-Python: <3.15,>=3.13
+Requires-Dist: ibis-framework<13,>=11
+Requires-Dist: numpy<3,>=2.1
+Requires-Dist: pyarrow<24,>=18
+Requires-Dist: pydantic<3,>=2.8.1
+Requires-Dist: pyyaml<7,>=6.0.2
+Requires-Dist: sqlglot<30,>=29
+Provides-Extra: airflow
+Requires-Dist: apache-airflow-providers-standard==1.20.1; extra == 'airflow'
+Requires-Dist: apache-airflow==3.3.2; extra == 'airflow'
+Provides-Extra: bigquery
+Requires-Dist: ibis-framework[bigquery]<13,>=12; extra == 'bigquery'
+Provides-Extra: dagster
+Requires-Dist: dagster==1.13.26; extra == 'dagster'
+Provides-Extra: dbt
+Requires-Dist: dbt-core==1.10.13; extra == 'dbt'
+Requires-Dist: dbt-duckdb==1.9.6; extra == 'dbt'
+Provides-Extra: diff-diff
+Requires-Dist: diff-diff==3.13.0; extra == 'diff-diff'
+Provides-Extra: doubleml
+Requires-Dist: doubleml==0.11.4; extra == 'doubleml'
+Provides-Extra: dowhy
+Requires-Dist: dowhy==0.14; (python_version < '3.14') and extra == 'dowhy'
+Provides-Extra: duckdb
+Requires-Dist: duckdb==1.5.6; extra == 'duckdb'
+Requires-Dist: ibis-framework[duckdb]<13,>=11; extra == 'duckdb'
+Provides-Extra: duckreg
+Requires-Dist: duckreg==0.4.1; extra == 'duckreg'
+Provides-Extra: increment
+Requires-Dist: increment==0.1.0a2; extra == 'increment'
+Provides-Extra: lifelines
+Requires-Dist: lifelines==0.30.3; extra == 'lifelines'
+Provides-Extra: pandas
+Requires-Dist: pandas<4,>=2.2; extra == 'pandas'
+Provides-Extra: polars
+Requires-Dist: polars<2,>=1.21; extra == 'polars'
+Provides-Extra: postgres
+Requires-Dist: ibis-framework[postgres]<13,>=12; extra == 'postgres'
+Provides-Extra: sketches
+Requires-Dist: datasketches<6,>=5.2; extra == 'sketches'
+Provides-Extra: snowflake
+Requires-Dist: ibis-framework[snowflake]<13,>=12; extra == 'snowflake'
+Description-Content-Type: text/markdown
+
+# terrine
+
+**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.
+
+## Why Terrine?
+
+Most data science datasets come in a few shapes:
+
+- snapshots with features and labels;
+- cohort curves;
+- time-to-event tables;
+- before-and-after windows around an event.
+
+Each time, the SQL is the same pile of date joins and window boundaries, rewritten by hand. Terrine takes the shape as a starting point. You name the rows you want and the windows to aggregate over; Terrine writes and runs the queries.
+
+Because Terrine knows each row's snapshot time, features can only look backwards and targets only forwards. Each value also says whether its window was fully covered by your data, so you decide how to treat gaps for your problem.
+
+## Example: a customer spend forecasting table
+
+Requires Python 3.13 or 3.14.
+
+```sh
+pip install --pre "terrine[duckdb,pandas]"
+```
+
+<!-- --8<-- [start:first-dataset] -->
+```python
+import ibis
+import pandas as pd
+import terrine as tr
+
+customers = pd.DataFrame({"customer_id": ["alice", "bob", "carol"]})
+orders = pd.DataFrame({
+    "customer_id": ["alice", "alice", "alice", "alice", "bob"],
+    "ordered_at": pd.to_datetime(
+        ["2025-01-03", "2025-01-20", "2025-02-10", "2025-03-05", "2025-01-05"]
+    ),
+    "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.
+model = tr.Model.from_tables(
+    con,
+    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"),
+    )},
+)
+
+# One row per customer every 28 days: 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",
+    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")),
+    },
+)
+
+data = design.build(model).to_pandas()
+columns = ["unit", "t0", "orders_30d", "spend_30d", "spend_next_30d", "spend_next_30d__reason"]
+print(data[columns].assign(t0=data["t0"].dt.date).sort_values(["t0", "unit"]).to_string(index=False))
+```
+<!-- --8<-- [end:first-dataset] -->
+
+```text
+ 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>
+carol 2025-02-01           0        0.0             0.0                   <NA>
+alice 2025-03-01           1       25.0            <NA>    incomplete_coverage
+  bob 2025-03-01           0        0.0            <NA>    incomplete_coverage
+carol 2025-03-01           0        0.0            <NA>    incomplete_coverage
+```
+
+(Only some columns are printed; `t0` is shown as a date.)
+
+Reading the output:
+
+- **Carol has no orders.** She still has a row at each snapshot, with zero counts.
+- **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.
+
+## 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 |
+| **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
+
+`tr.recipes` covers the usual shapes. Each one returns a normal `Design` you can edit.
+
+| You want | Recipe | Guide |
+| --- | --- | --- |
+| Forecasting, propensity and other features-plus-target tables | `time_series` | [Scheduled time series](https://github.com/kylejcaron/terrine/blob/main/docs/guides/temporal-engine.md#scheduled-time-series) |
+| Customer lifetime value curves by cohort | `ltv` | [Cumulative LTV](https://github.com/kylejcaron/terrine/blob/main/docs/guides/trajectories-survival.md#cumulative-ltv) |
+| Time-to-event / survival analysis | `survival`, `life_table` | [Survival records](https://github.com/kylejcaron/terrine/blob/main/docs/guides/trajectories-survival.md#survival-records) |
+| Behavior before and after an event (event study) | `event_panel` | [Event panels](https://github.com/kylejcaron/terrine/blob/main/docs/guides/sequential-panels.md#event-panels) |
+| Repeated eligibility for observational "trials" | `trial_panel` | [Trial panels](https://github.com/kylejcaron/terrine/blob/main/docs/guides/sequential-panels.md#scheduled-trial-panels) |
+| State changes such as plan upgrades and downgrades | `state_panel` | [State panels](https://github.com/kylejcaron/terrine/blob/main/docs/guides/state-panels.md) |
+| Ordered events in a window after an event, up to a set count | `event_sequence` | [Event sequences](https://github.com/kylejcaron/terrine/blob/main/docs/guides/temporal-engine.md#bounded-event-sequences-and-event-time-origins) |
+
+More feature recipes are in [common feature patterns](https://github.com/kylejcaron/terrine/blob/main/docs/guides/common-feature-patterns.md): recency, "active in the last N days" filters, attributes as of t0, conversions after a purchase, and true/false labels.
+
+## Where it runs
+
+Queries run where your data lives; nothing is uploaded. Results come back as pandas, Polars or Arrow.
+
+| Backend | Status |
+| --- | --- |
+| DuckDB | Reference backend; can also save versioned datasets |
+| PostgreSQL 16, BigQuery, Snowflake | Verified against DuckDB; floating-point results match within documented tolerances |
+| Other Ibis backends | Read-only, unverified; opt in with `allow_unverified=True` |
+
+See [backend compatibility](https://github.com/kylejcaron/terrine/blob/main/docs/guides/backend-compatibility.md) for extras and details.
+
+## Learn more
+
+- [Your first dataset](https://github.com/kylejcaron/terrine/blob/main/docs/guides/first-dataset.md): this example step by step, with output limits and saved datasets.
+- [Training and scoring sets](https://github.com/kylejcaron/terrine/blob/main/docs/guides/ml-staging.md): reproducible train/score tables and saved definitions.
+- [Library hand-offs](https://github.com/kylejcaron/terrine/blob/main/docs/guides/library-handoffs.md): pass datasets to modeling libraries. Terrine builds data and makes no causal claims.
+- [All guides](https://github.com/kylejcaron/terrine/blob/main/docs/guides/index.md), [limitations](https://github.com/kylejcaron/terrine/blob/main/docs/guides/limitations.md) and [error codes](https://github.com/kylejcaron/terrine/blob/main/docs/reference/refusals.md).
+
+Contributing? See [CONTRIBUTING.md](https://github.com/kylejcaron/terrine/blob/main/CONTRIBUTING.md).
+
+## License
+
+[Apache License 2.0](https://github.com/kylejcaron/terrine/blob/main/LICENSE); see [NOTICE](https://github.com/kylejcaron/terrine/blob/main/NOTICE).