grain 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a98d985852245285e65d2e58f8a2ae02e2c998f58d49ee70ef5f99f3b13e3d9
-  data.tar.gz: 7ee5d68d74314f57bbcd0315e4cd9c9d0b2b79d2b2ffd8e3a376d5e09c8c537a
+  metadata.gz: 2bef8d3a722d2241abb6bc04ed91d129879f623c3649e9cf24fbcd2cb1064513
+  data.tar.gz: 404159a851fd37121235e0f4339b27b71706fd13fda285336502bfbcaf15384a
 SHA512:
-  metadata.gz: 48aa997aee1584516efc868aac66685a54d6c6b1caf89a70a10d7e42259023eac2e1c4575dc86fc2e95e42378295bb512081028ea70725897f888ef3bd8774f2
-  data.tar.gz: 2d78ba7b8411d9bf0146c8bb6c458958e6f12c7c89c61397e34d0047fe312ac8a3562d0c88b7959b99d569b050385329daf8b38c99e314e15a4da96266f7b8c1
+  metadata.gz: 347e30664fa16280bdae9cb1df3dd1c4fd3d4b33857f90ee539ccc5646856ce63a0c73ebd0c7ff2a55aa83ff6b3f8efc0565feb8821b1c9c13204cb6e0a0eb20
+  data.tar.gz: 337d6e981b43a9471427a6069823d114fd535f9d0a5fac1bb5efe303cc7c164de1997eed8c5d3754f5c76649569b84c2ba8b17672b837357a5786723a49ea7cd

data/CHANGELOG.md

@@ -1,5 +1,95 @@
 ## [Unreleased]
 
+## [0.0.3] - 2026-08-21
+
+### Fixed
+
+- **Generated migrations tripped the linter of the app they landed in.** They
+  wrote `[ :a, :b ]` as `[:a, :b]`, and `rubocop-rails-omakase` — which ships with
+  every `rails new` on Rails 8 — wants the inner spaces. It lints `db/migrate`;
+  `db/schema.rb` is the excluded one. So installing Grain put an application's
+  linter in the red over a file it had not written, and regenerating the migration
+  after a definition changed, which Grain asks for, brought the offence back.
+
+## [0.0.2] - 2026-08-21
+
+Everything here came out of using Grain in two real applications: a football
+pool (golbet) and a multi-tenant church management API (ekklesia).
+
+### Breaking
+
+- **Reads require their tenant.** `Rollup.by(...)` without a `for(tenant: ...)`
+  now raises `Grain::MissingTenantError` instead of aggregating every tenant into
+  one number. The read it replaces did not return a wrong figure, it returned
+  another tenant's, and nothing about the result gave that away. A `nil` tenant is
+  refused for the same reason: no cell can hold one, so the read came back a clean
+  zero. Spanning every tenant is asked for by name with `Rollup.across_tenants`,
+  which also makes those reads greppable.
+- **Joined tables are aliased `g_<path>` instead of `j0`, `j1`.** Named by the
+  whole association path, because two routes can end at the same table and one
+  alias for both is ambiguous. A measure expression written against a generated
+  alias has to be updated.
+- **Tables a measure reads through now log every update**, which changes the
+  triggers a rollup installs. Regenerate the table migration for every rollup that
+  uses `through:` — see Upgrading.
+
+### Added
+
+- **`through:` on a measure**, so an expression can read columns from tables the
+  fact joins to: `sum: "CASE WHEN g_match.status = 'finished' THEN 1 ELSE 0 END",
+  through: :match`. Those tables are joined into the recompute and watched by the
+  triggers, because a column they own can change what a measure computes without
+  any fact row moving.
+- **`Grain::Installer.install!` and `rake grain:triggers`**, which re-attach the
+  trigger function and every trigger. Needed after any `schema.rb` load: the
+  schema format cannot represent functions or triggers, so loading it creates the
+  tables and silently drops everything that keeps them correct. That is how test
+  databases are built and what `db:reset` does.
+- **`Grain::DrainJob`** and `config.queue`, so keeping rollups fresh is a
+  scheduled ActiveJob entry rather than a cron line invoking rake. Overlapping
+  runs are safe: claiming uses `FOR UPDATE SKIP LOCKED`.
+
+### Fixed
+
+- **A change to a table only a measure read never reached the rollup.** The
+  trigger fired and the log took the row, but the registry did not route that
+  table to any rollup, so the worker dropped it and the aggregate drifted in
+  silence — the one failure mode Grain exists to prevent.
+- **Rollup discovery `require`d files Zeitwerk manages**, which either
+  double-defines the class or fails outright. It constantizes them now, and no
+  longer blows up when `app/rollups` does not exist.
+- **The railtie pushed `app/rollups` into `autoload_paths`** from an initializer,
+  by which point that array is frozen. Rails already autoloads and eager loads
+  everything under `app/`, so the hook was both broken and unnecessary.
+- `for(dimension: [])` raised a Postgres syntax error from `IN ()`. An empty list
+  is what `current_user.churches.ids` hands over when there are none, and it now
+  matches nothing instead of failing.
+- `for(dimension: [id, nil])` silently dropped the null coordinate: `IN` treats a
+  null as an unknown that equals nothing, so the cells with no value for that
+  dimension — the ones a dashboard labels "uncategorised" — fell out of the answer
+  with no sign they had been left out. A list containing `nil` now matches them,
+  the same as passing `nil` on its own already did.
+- A `time` dimension resolved from a **nullable** column is now reported as
+  nullable, so the rollup takes the surrogate key path instead of declaring the
+  bucket `NOT NULL` inside the primary key. Before this, the first fact row with
+  no timestamp failed to insert — at write time, on the application's own table,
+  with nothing pointing at Grain.
+- The install generator's closing instructions named the wrong generator for
+  step 3.
+
+### Upgrading from 0.0.1
+
+1. Any read without a tenant now raises. Add `for(tenant: ...)`, or
+   `across_tenants` where crossing them is the point.
+2. Rename generated join aliases in measure expressions: `j0` becomes
+   `g_<association path>`.
+3. Regenerate and run the table migration for every rollup
+   (`bin/rails generate grain:table <Rollup>`), so the triggers cover the tables
+   your measures read through.
+4. Call `Grain::Installer.install!` wherever your test suite loads the schema.
+   Without it the triggers do not exist in the test database, the rollups never
+   update, and the suite passes anyway.
+
 ## [0.0.1] - 2026-08-19
 
 First published release. Feature complete for a first pass and tested end to end

data/CLAUDE.md

@@ -0,0 +1,154 @@
+# Grain — contexto del proyecto
+
+Gema Ruby: **agregados pre-calculados y mantenidos incrementalmente dentro del Postgres de la
+propia aplicación**, para que los dashboards de Rails respondan en milisegundos. Publicada como
+`grain` 0.0.1 en RubyGems. El repo remoto (`github.com/grainrb/grain`) todavía no existe.
+
+Documentos hermanos: `../proyecto-grain.md` (plan de negocio, modelo open core, criterios para
+matar el proyecto), `../ideas-negocio.md`, `../ekklesia/CLAUDE.md` (integración en curso).
+
+## Estado
+
+- **208 tests, 0 fallas. Rubocop limpio.** `bundle exec rake` corre ambos.
+- Alcance de la v1 **completo**: definición, esquema, generadores, triggers, worker, `verify`,
+  backfill, API de lectura, `DrainJob`.
+- **Probada en una app real** (`../golbet`, porras de fútbol): coincide con la implementación de
+  referencia en Ruby y lee entre 6x y 62x más rápido.
+- **Segunda app, completa** (`../ekklesia`, multi-tenant de verdad con `acts_as_tenant`): dos
+  rollups, `verify` limpio, 26 specs que los comparan contra los endpoints que reemplazan, el
+  worker programado con Solid Queue (probado en Linux: el drenado ocurre solo) y los tres endpoints
+  de `stats` ya leyendo el rollup. Salieron tres cambios de ahí: las lecturas exigen tenant
+  (incompatible), la dimensión de tiempo nulable, y los filtros de lista con `nil` o vacíos.
+  Detalle en `../ekklesia/CLAUDE.md`.
+- **Hay cambios sin commitear** en grain y en golbet (DrainJob, Installer, README). Los commits
+  los hace el usuario; yo redacto los mensajes y no ejecuto `git commit`.
+- **0.0.2 publicada.** 0.0.3 lista para publicar, sin publicar: un arreglo, que las migraciones
+  generadas pasen `rubocop-rails-omakase`.
+- (histórico) **0.0.2 lista para publicar, sin publicar.** Versión bumpeada, CHANGELOG escrito con sección de
+  Upgrading, descripción del gemspec corregida, bloque de estado del README al día, y
+  `grain-0.0.2.gem` construida. Falta `git push` y `gem push`, que los hace el usuario.
+
+## Cómo trabajar aquí
+
+```bash
+docker run -d --name grain-pg -e POSTGRES_PASSWORD=grain \
+  -e POSTGRES_DB=grain_test -p 5433:5432 postgres:18
+bundle exec rake          # tests + rubocop
+```
+
+Los tests de integración se saltan solos si no hay Postgres. `GRAIN_TEST_DATABASE_URL` lo
+reapunta. Los tests corren los generadores de verdad, cargan los archivos que escriben y los
+aplican a la base viva: **afirmar sobre strings generados es confianza falsa**, y ya pasó tres
+veces que un string perfecto era semánticamente incorrecto.
+
+## La API
+
+```ruby
+class OrderRevenueRollup < Grain::Rollup
+  fact LineItem, where: { order: { state: "paid" } }
+
+  tenant    :store_id,    via: { order: :store_id }        # obligatorio
+  time      :ordered_on,  via: { order: :placed_on }, grain: :day   # opcional
+  dimension :product_id,  via: :product_id                  # columna local
+  dimension :category_id, via: { product: :category_id }    # un salto
+  dimension :currency,    via: { order: :currency }, immutable: true
+
+  measure :line_count,    count: true
+  measure :revenue_cents, sum: "quantity * unit_price_cents", type: :bigint
+  measure :paid_lines,    sum: "CASE WHEN g_order.state = 'paid' THEN 1 ELSE 0 END",
+                          type: :bigint, through: :order
+  ratio   :average_unit_price, of: :revenue_cents, over: :line_count
+end
+```
+
+Generadores: `grain:install` (una vez), `grain:rollup NAME` (esqueleto), `grain:table NAME`
+(migración de tabla + triggers; **regenerar cada vez que cambia la definición**).
+Tareas: `grain:drain`, `grain:verify` (sale con código != 0), `grain:backfill ROLLUP=`,
+`grain:triggers`.
+API: `Rollup.for(...).between(...).by(...)`, `.verify(repair:)`, `.backfill(from:, pause:)`,
+`Grain::Worker.drain`, `Grain::DrainJob`, `Grain::Installer.install!`.
+
+## Decisiones tomadas — no relitigar
+
+1. **Recomputar una celda es la primitiva; los deltas son la optimización, y la v1 no los tiene.**
+   El worker trabaja por lotes, así que 1000 inserts en 10 celdas son 10 recomputaciones.
+2. **La regla que gobierna todo**: recomputar una celda que no hacía falta es inofensivo; no
+   recomputar una que sí, es el único bug imperdonable. Ante la duda, recomputa.
+3. **Recomputar es DELETE + INSERT, no upsert.** Una celda puede quedar legítimamente vacía y un
+   upsert dejaría los números viejos para siempre.
+4. **Solo cadenas `belongs_to`, máximo 3 saltos.** Es aritmética: por `belongs_to` cada fila de
+   hecho cae en exactamente una celda. Cruzar un `has_many` duplicaría cada conteo.
+5. **`tenant` obligatorio, `time` opcional.** Sin `time` el rollup es un counter cache verificable.
+6. **`sum`/`min`/`max` exigen `type:` explícito.** Adivinar redondearía la plata de alguien.
+7. **Un trigger por tabla fuente, nunca por rollup**, y la lista de columnas es la **unión** entre
+   todos los rollups que la vigilan.
+8. **Las tablas de hechos y las que leen las medidas registran todos los updates** (SQL arbitrario,
+   no se sabe qué columnas lo alimentan). Las demás se reducen con precisión.
+9. **Alias `f` para el hecho, `g_<camino>` para los joins.** Por el camino completo, no el último
+   salto: dos rutas pueden terminar en la misma tabla.
+10. **Los ratios se guardan en dos partes y se dividen al leer.** Nunca pre-divididos.
+11. **Grain emite archivos de migración**, no crea tablas en runtime, y la migración es una
+    fotografía (el SQL va literal, no leído de la gema).
+12. **Las lecturas exigen el tenant; cruzarlo se pide por su nombre** (`across_tenants`). Una
+    lectura sin tenant no devuelve un número equivocado, devuelve el de otro inquilino, y no hay
+    default seguro que Grain pueda elegir: no sabe de quién es el dato que le toca a quien
+    pregunta. Un tenant `nil` se rechaza igual, porque ninguna celda puede tener uno y la lectura
+    volvería como un cero limpio. La escotilla existe porque el caso legítimo existe (un panel de
+    administración), y así queda greppable.
+13. **Los agregados se castean al tipo declarado.** `SUM` sobre `bigint` da `numeric`; sin el cast
+    hay falsos positivos permanentes en `verify` y `BigDecimal` en las lecturas.
+
+## Patrones de bug que ya morderon — no reintroducir
+
+- **`schema.rb` no representa funciones ni triggers.** Cargar el esquema (así se construyen las
+  bases de test, y así funciona `db:reset`) crea las tablas y borra todo lo que las mantiene
+  correctas. Sin señal alguna. Se arregla con `Grain::Installer.install!`.
+- **Los tests que leen un rollup tienen que drenar.** Incluido uno que muta datos después de que
+  su propio setup ya drenó.
+- **ActiveRecord reporta `bigint` como `:integer` con `limit: 8`.** Tomarlo literal da llaves de
+  4 bytes contra fuentes de 8.
+- **`create_table primary_key: [...]` junto con `id: false`** no crea llave primaria alguna, en
+  silencio.
+- **`Array({a: :b})`** convierte el hash en pares.
+- **Enseñarle a los triggers a vigilar una tabla sin enseñárselo al `Registry`**: el trigger
+  dispara, el log se llena, el worker la ignora.
+- **`FULL OUTER JOIN` en Postgres no acepta `IS NOT DISTINCT FROM`.** `verify` usa `UNION ALL` +
+  `GROUP BY`, que además ya trata los nulos como iguales.
+- **Afirmar sobre números sin afirmar el tipo.** `assert_equal 1400, BigDecimal(1400)` pasa.
+- **El código que Grain emite tiene que pasar el linter de la app donde cae.** Las migraciones
+  escribían `[:a, :b]` y `rubocop-rails-omakase` —el default de todo `rails new` en Rails 8, y que
+  sí linea `db/migrate`— quiere `[ :a, :b ]`. Instalar la gema dejaba el linter en rojo por un
+  archivo que la app no escribió. El `.rubocop.yml` de Grain no usa omakase, por eso no se veía.
+- **`[nil].any?` es `false`, y `[false].any?` también.** Preguntar por verdadez si una lista de
+  valores trae algo tira justo los valores que hay que tratar. Va con `empty?`. Recién mordió al
+  arreglar los filtros de lista: el `IS NULL` no se agregaba nunca y el `nil` de la lista
+  desaparecía en silencio, que es el bug que se estaba arreglando.
+- **`IN` trata al nulo como desconocido, no como coordenada.** `for(dim: [id, nil])` dejaba fuera
+  las celdas sin valor —las que un panel muestra como "sin categoría"— sin señal. Y `IN ()` no es
+  SQL válido: una lista vacía es `FALSE`, no un error de sintaxis.
+- **Tratar una dimensión de tiempo como exenta de la nulabilidad de su fuente.** Guarda un bucket,
+  no el timestamp, pero el bucket de un nulo es nulo. Declararlo `NOT NULL` dentro de la llave
+  primaria hacía fallar el primer insert **en la tabla de hechos de la app**, lejos de Grain.
+
+## Limitaciones vigentes (están en el README)
+
+Solo Postgres (15+ si alguna dimensión es nulable). Solo medidas aditivas — sin conteos distintos
+ni percentiles (necesitan HyperLogLog / t-digest, y son **Grain Pro**). Solo grano diario. Un
+hecho por rollup, sin rollups sobre rollups (Pro). Sin deltas. `pause:` es espera fija, no
+throttling adaptativo por lag de replicación. Un rollup con modelo roto se salta con advertencia.
+
+## Lo que sigue
+
+1. ~~Bloque de estado del README, descripción del gemspec, CHANGELOG, versión~~ — **hecho**. Falta
+   `git push`, `gem push grain-0.0.2.gem` y el tag `v0.0.2`. Ojo con el tag: **`v0.0.1` quedó en un
+   commit donde `version.rb` todavía decía 0.0.0**, así que no marca lo que se publicó. Poner
+   `v0.0.2` en el commit del bump, no antes.
+2. 0.0.2 lleva **tres cambios incompatibles**: tenant obligatorio en las lecturas, alias de joins
+   `g_<camino>` en vez de `j0`, y triggers nuevos en las tablas que leen las medidas (hay que
+   regenerar las migraciones de tabla). Están en el CHANGELOG con su sección de Upgrading. Ni
+   golbet ni ekklesia se rompen: las dos corren verdes contra 0.0.2.
+3. El artículo fundacional: *"Cómo matamos nuestras vistas materializadas"*, con los números de
+   golbet. Según `../proyecto-grain.md` es todo el mercadeo del primer año.
+4. **Las 5-10 conversaciones con equipos Rails que tengan dashboards pesados.** Sigue sin hacerse,
+   y es el criterio de muerte escrito en frío: si nadie reconoce el problema como serio, no hay
+   negocio. El código va muy adelante de la validación.

data/README.md

@@ -31,11 +31,14 @@ OrderRevenueRollup.for(store: current_store)
 
 > ### Status
 >
-> Version 0.0.1. Feature complete for a first pass and tested end to end against
-> a live PostgreSQL, including the generators, the triggers, the worker,
-> verification, backfilling and reads. **Not yet used in a real application**, so
-> the API may still change. Treat it as something to read and argue with rather
-> than something to put in front of customers this week.
+> Version 0.0.2, and **in use in two real applications**: a football pool, where
+> it agrees with the Ruby implementation it replaced and reads between 6x and 62x
+> faster, and a multi-tenant church management API, where its dashboard endpoints
+> now read rollups. Everything in 0.0.2 came out of that — including one breaking
+> change, so read the CHANGELOG before upgrading.
+>
+> Still 0.x. The API can still change, and the limitations below are real rather
+> than theoretical.
 
 ## The problem
 
@@ -112,7 +115,19 @@ what makes it true about the past.
 $ bin/rails grain:drain
 ```
 
-Run that on a schedule, or call `Grain::Worker.drain` from a job of your own.
+Or schedule `Grain::DrainJob`, which does the same thing from ActiveJob:
+
+```yaml
+# config/recurring.yml, with Solid Queue
+production:
+  grain_drain:
+    class: Grain::DrainJob
+    schedule: every minute
+```
+
+Overlapping runs are safe and need no guard: claiming uses `FOR UPDATE SKIP
+LOCKED`, so two drains at once split the work rather than repeat it. A slow run
+caught by the next tick is not a problem.
 
 **5. Read it.**
 
@@ -145,6 +160,8 @@ workspace, an organisation.
 tenant :store_id, via: { order: :store_id }
 ```
 
+Reads refuse to run without it. See [Reading](#reading).
+
 ### `time` — optional
 
 The bucket rows fall into. Only `grain: :day` in this release.
@@ -160,6 +177,11 @@ Timestamps are resolved to a calendar day in an explicit zone (`config.time_zone
 UTC by default). Left to the database session, the same row would land in
 different buckets for different callers.
 
+A nullable source column is allowed, and the rows with no timestamp collect in a
+null bucket — the bucket of a null is null, so the rollup takes the surrogate key
+path like any other nullable dimension. If those rows have no business being in
+the aggregate at all, keep them out with the fact's `where:` instead.
+
 ### `dimension`
 
 ```ruby
@@ -188,8 +210,31 @@ measure :revenue_cents, sum: "quantity * unit_price_cents", type: :bigint
 measure :largest_line,  max: "quantity * unit_price_cents", type: :bigint
 ```
 
-`count`, `sum`, `min` and `max`. Expressions are your own SQL over the fact table,
-which is aliased `f` if you need to qualify a column.
+`count`, `sum`, `min` and `max`. Expressions are your own SQL. The fact table is
+aliased `f`.
+
+An expression can read columns from a related table by declaring the associations
+it needs with `through:`. Joined tables are aliased `g_` plus the path that
+reaches them, so the expression stays readable:
+
+```ruby
+measure :paid_lines,
+        sum: "CASE WHEN g_order.state = 'paid' THEN 1 ELSE 0 END",
+        type: :bigint,
+        through: :order
+
+measure :local_cents,
+        sum: "CASE WHEN g_order_store.currency = 'COP' THEN f.quantity * f.unit_price_cents ELSE 0 END",
+        type: :bigint,
+        through: { order: :store }
+```
+
+Grain watches every table a measure reads, so changing one of those columns
+rebuilds the affected cells even though no fact row moved. Those tables log
+**every** update rather than a narrowed set, for the same reason the fact table
+does: the expression is arbitrary SQL and there is no telling which of its
+columns feed the measure. That is a real cost — weigh it before pointing a
+measure at a table that is written constantly.
 
 `sum`, `min` and `max` require an explicit `type:`. `count` does not, since
 counting rows always yields an integer. The others aggregate arbitrary SQL whose
@@ -274,8 +319,14 @@ mine.by(:product_id).to_h                  # keyed by group
 mine.sql                                   # the statement, for when you want to look
 ```
 
+- **The tenant is required.** A read that does not name one raises
+  `Grain::MissingTenantError` rather than totalling every tenant at once. That
+  read does not return a wrong number, it returns somebody else's, and nothing
+  about the result looks unusual — so it fails instead of warning. Grain has no
+  safe default here: it cannot know whose data the caller is entitled to.
 - **`for`** filters any dimension. Values may be ids, ActiveRecord objects,
-  arrays, or `nil` (which matches a null coordinate).
+  arrays, or `nil` (which matches a null coordinate). A `nil` *tenant* is refused
+  too: no cell can have one, so the read would come back a clean, wrong zero.
 - **`between`** takes two dates or a range.
 - **`by`** groups. Coarsen the time bucket with `by(ordered_on: :month)` —
   `:day`, `:week`, `:month`, `:quarter`, `:year`.
@@ -288,6 +339,16 @@ mine.sql                                   # the statement, for when you want to
 - Narrowing returns a new query, so a base query can be handed around and reused.
 - Results come back typed — `Date` and `Integer`, not the driver's strings.
 
+Spanning every tenant is a real thing to want — a platform-wide total, an admin
+dashboard — and it is asked for by name:
+
+```ruby
+OrderRevenueRollup.across_tenants.by(:product_id).revenue_cents
+```
+
+Grepping for `across_tenants` then lists every read that crosses the boundary,
+which is not something you can do with an omission.
+
 ## Backfilling
 
 ```ruby
@@ -368,6 +429,54 @@ silence. Precise where it can be, conservative where it cannot.
 The column list is the union across every rollup that watches a table, so adding
 a rollup never narrows a trigger another one depends on.
 
+## Triggers and schema loading
+
+**`schema.rb` cannot represent a function or a trigger.** Rails' schema dumper
+knows tables, columns and indexes, and nothing else, so loading a schema creates
+every table and silently drops everything that keeps them correct. That is how
+test databases are built by default, and what `db:reset` and restoring a dump both
+do — leaving a rollup that never updates and a test suite that passes anyway.
+
+Re-attach them after any schema load:
+
+```console
+$ bin/rails grain:triggers
+```
+
+```ruby
+Grain::Installer.install!   # safe to call any number of times
+Grain::Installer.installed? # false right after a schema load
+```
+
+In a test suite, put it where the database is prepared:
+
+```ruby
+# test/test_helper.rb
+class ActiveSupport::TestCase
+  Grain::Installer.install!
+end
+```
+
+### Tests that read a rollup have to drain
+
+A page backed by a rollup only shows what the worker has already applied, and in a
+test nothing is running one. Any test that writes and then reads a rollup — or
+renders something that does — has to drain in between:
+
+```ruby
+Prediction.create!(...)
+Grain::Worker.drain
+get standings_path
+```
+
+That includes a test that mutates data *after* its own setup already drained. This
+is real friction, and the first thing to check when a test that should show new
+numbers shows the old ones.
+
+The other option is `config.active_record.schema_format = :sql`, which dumps
+through `pg_dump` and keeps functions and triggers. That is the more thorough fix
+and a bigger change to how an application works, so Grain does not assume it.
+
 ## Configuration
 
 ```ruby
@@ -376,6 +485,7 @@ Grain.configure do |config|
   config.change_log_table = "grain_change_log"  # baked into the trigger function
   config.batch_size = 1_000                     # change log rows claimed per transaction
   config.max_run_seconds = 30                   # how long a drain may run before yielding
+  config.queue = :default                       # queue Grain::DrainJob runs on
   config.time_zone = "UTC"                      # the zone day buckets are cut in
   config.logger = Rails.logger
 end
@@ -403,15 +513,16 @@ Stated plainly, because finding these out later is worse than reading them now.
   no percentiles: neither can be maintained without reading the rest of the cell's
   source rows, which needs sketches (HyperLogLog, t-digest) rather than a column.
 - **`belongs_to` chains only**, three hops deep. No `has_many`, no join tables.
+  This applies to a measure's `through:` as much as to a dimension's `via:`.
 - **Daily grain only.** No hourly buckets yet.
 - **One fact per rollup.** No joins between facts, and no rollups built on rollups.
 - **No deltas.** The worker recomputes affected cells rather than incrementing
   them. Batching makes this fine in ordinary use — a thousand inserts landing in
   ten cells cost ten recomputes — but a single enormous cell is recomputed in full
   every time it is touched.
-- **No job integration.** There is no ActiveJob class yet: run `rake grain:drain`
-  on a schedule or call `Grain::Worker.drain` from a job of your own.
 - **`pause:` is a fixed wait**, not adaptive throttling on replication lag.
+- **Triggers do not survive a `schema.rb` load** and have to be re-attached with
+  `rake grain:triggers`. See above; this catches everyone once.
 - **A rollup with a broken model reference is skipped with a warning** rather than
   raising, so one bad rollup cannot stop the log from draining. Watch your logs.
 

data/lib/generators/grain/install/install_generator.rb

@@ -35,8 +35,8 @@ module Grain
         say ""
         say "Grain installed. Next:", :green
         say "  1. bin/rails db:migrate"
-        say "  2. Declare a rollup in app/rollups"
-        say "  3. bin/rails generate grain:rollup <name>  (to build its table and triggers)"
+        say "  2. bin/rails generate grain:rollup <name>   (writes a definition to fill in)"
+        say "  3. bin/rails generate grain:table <name>    (builds its table and triggers)"
         say ""
       end
 

data/lib/generators/grain/install/templates/initializer.rb.erb

@@ -14,4 +14,7 @@ Grain.configure do |config|
   # monopolise a queue slot.
   config.max_run_seconds = 30
 
+  # Queue Grain::DrainJob runs on.
+  config.queue = :default
+
 end

data/lib/grain/configuration.rb

@@ -15,6 +15,9 @@ module Grain
     # monopolise a job queue slot.
     attr_accessor :max_run_seconds
 
+    # ActiveJob queue Grain::DrainJob runs on.
+    attr_accessor :queue
+
     # Time zone the day buckets are cut in. A timestamp has to be resolved to a
     # calendar day in some zone, and leaving it to the database session would make
     # the same row land in different buckets depending on who ran the query.
@@ -27,6 +30,7 @@ module Grain
       @change_log_table = "grain_change_log"
       @batch_size = 1_000
       @max_run_seconds = 30
+      @queue = :default
       @time_zone = "UTC"
       @logger = nil
     end

data/lib/grain/definition.rb

@@ -93,6 +93,14 @@ module Grain
       watched_paths.flat_map(&:hops).uniq
     end
 
+    # Associations a measure's expression reads columns from. Their joins have to
+    # exist for the expression to resolve, and their tables have to be watched: a
+    # match's score changing alters what a measure computes even though no fact
+    # row moved.
+    def measure_paths
+      measures.flat_map(&:through).uniq
+    end
+
     # Associations the fact's filter reaches through. A change there adds or
     # removes fact rows entirely, which no delta can express.
     def filter_associations

data/lib/grain/drain_job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Grain
+  # Drains the change log from a background job, so keeping rollups fresh is a
+  # scheduled entry rather than a cron line invoking rake.
+  #
+  # Overlapping runs are safe and need no guard. Claiming uses FOR UPDATE SKIP
+  # LOCKED, so two of these at once split the work instead of fighting over it or
+  # doing it twice — a slow run caught by the next tick is not a problem.
+  #
+  # Loaded only when ActiveJob is, so the gem does not depend on it.
+  class DrainJob < ActiveJob::Base
+    queue_as { Grain.config.queue }
+
+    def perform(limit: nil, max_seconds: nil)
+      Worker.drain(**{ limit: limit, max_seconds: max_seconds }.compact)
+    end
+  end
+end

data/lib/grain/errors.rb

@@ -16,6 +16,10 @@ module Grain
   # `verify` found rows where the rollup disagrees with its source.
   class VerificationError < Error; end
 
+  # A rollup keyed by tenant was read without one. Not a wrong number: somebody
+  # else's number, which is why it raises instead of warning.
+  class MissingTenantError < Error; end
+
   # No rollup class matches the name a command was given.
   class RollupNotFoundError < Error; end
 

data/lib/grain/installer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Grain
+  # Recreates the trigger function and every trigger from the current definitions.
+  #
+  # This is needed far more often than it looks. Rails' schema.rb cannot represent
+  # a function or a trigger — the dumper only knows tables, columns and indexes —
+  # so loading the schema creates every table and silently drops everything that
+  # keeps them correct. That is how test databases are built by default, and what
+  # `db:reset` and restoring a dump both do. Without re-attaching, a rollup simply
+  # never updates, and the tests that should have caught it pass.
+  #
+  # Safe to run at any time: the function is CREATE OR REPLACE and each trigger is
+  # dropped before being created.
+  module Installer
+    class << self
+      # Returns the tables triggers were attached to.
+      def install!(definitions = default_definitions)
+        return [] if definitions.empty?
+
+        triggers = Triggers.new(definitions)
+        connection.execute(ChangeLog.function_sql)
+        triggers.up_statements.each { |statement| connection.execute(statement) }
+        triggers.specs.map(&:table)
+      end
+
+      # True when the change log's function is present, which is the cheap way to
+      # tell a schema load has stripped Grain out.
+      def installed?
+        connection.select_value(<<~SQL).present?
+          SELECT proname FROM pg_proc WHERE proname = '#{ChangeLog::FUNCTION_NAME}'
+        SQL
+      end
+
+      private
+
+      def default_definitions
+        Registry.all.map(&:definition)
+      end
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+    end
+  end
+end

data/lib/grain/join_graph.rb

@@ -11,6 +11,12 @@ module Grain
     # verbatim, so this is the name they can qualify columns with.
     FACT = "f"
 
+    # Joined tables are aliased by the association path that reaches them, so an
+    # expression can read `g_match.home_score` rather than a generated j0. The
+    # prefix keeps the alias clear of SQL keywords: `belongs_to :order` would
+    # otherwise produce `order`, which does not parse.
+    ALIAS_PREFIX = "g_"
+
     Joined = Struct.new(:name, :model, :on, keyword_init: true)
 
     attr_reader :definition, :types
@@ -53,11 +59,16 @@ module Grain
     private
 
     def register_all
-      definition.key_dimensions.reject { |dimension| dimension.path.local? }
-                .each { |dimension| register(dimension.path.hops) }
+      dimension_hops.each { |hops| register(hops) }
+      definition.measure_paths.each { |path| register(path.hops) }
       definition.filter_associations.each { |association| register([association]) }
     end
 
+    def dimension_hops
+      definition.key_dimensions.reject { |dimension| dimension.path.local? }
+                .map { |dimension| dimension.path.hops }
+    end
+
     # A local column needs no join, so an empty path is a caller's mistake rather
     # than a base case: treating it as one recurses forever.
     def register(hops)
@@ -69,7 +80,9 @@ module Grain
 
     def join_for(hops, parent)
       reflection = types.reflection!(parent.model, hops.last, hops.join("."))
-      name = "j#{@joined.size}"
+      # Named by the whole path rather than the last hop: two different routes can
+      # end at the same table, and one alias for both would be ambiguous.
+      name = "#{ALIAS_PREFIX}#{hops.join("_")}"
       Joined.new(name: name, model: reflection.klass, on: "#{name}.id = #{parent.name}.#{reflection.foreign_key}")
     end
 

data/lib/grain/measure.rb

@@ -20,15 +20,17 @@ module Grain
     # revenue. The declaration is one word, and it is cheap insurance.
     COUNT_TYPE = :bigint
 
-    attr_reader :name, :aggregate, :expression, :type
+    attr_reader :name, :aggregate, :expression, :type, :through
 
     def self.from_options(name, options)
       options = options.dup
       type = options.delete(:type)
+      through = options.delete(:through)
       reject_ambiguous_aggregate!(name, options)
 
       aggregate, value = options.first
-      new(name: name, aggregate: aggregate, expression: value == true ? nil : value, type: type)
+      new(name: name, aggregate: aggregate, expression: value == true ? nil : value,
+          type: type, through: through)
     end
 
     def self.reject_ambiguous_aggregate!(name, options)
@@ -39,11 +41,12 @@ module Grain
     end
     private_class_method :reject_ambiguous_aggregate!
 
-    def initialize(name:, aggregate:, expression: nil, type: nil)
+    def initialize(name:, aggregate:, expression: nil, type: nil, through: nil)
       @name = name.to_sym
       @aggregate = aggregate.to_sym
       @expression = expression
       @type = (type || (@aggregate == :count ? COUNT_TYPE : nil))&.to_sym
+      @through = wrap(through).map { |path| Path.parse_association(path) }.freeze
       validate!
       freeze
     end
@@ -71,6 +74,16 @@ module Grain
 
     private
 
+    # Not Array(), which turns a Hash into a list of pairs and would take
+    # `through: { order: :store }` apart into two unrelated associations.
+    def wrap(through)
+      case through
+      when nil then []
+      when Array then through
+      else [through]
+      end
+    end
+
     def validate!
       validate_aggregate!
       validate_expression!

data/lib/grain/migration.rb

@@ -43,6 +43,15 @@ module Grain
 
     private
 
+    # Array#inspect renders [:a, :b], and rubocop-rails-omakase wants the inner
+    # spaces. That matters because omakase ships with every `rails new` on Rails 8
+    # and lints db/migrate — db/schema.rb is excluded, migrations are not. Without
+    # this, installing Grain puts an application's linter in the red over a file it
+    # did not write, and regenerating the migration brings the offence back.
+    def symbol_list(names)
+      "[ #{names.map(&:inspect).join(", ")} ]"
+    end
+
     def create_table
       lines = ["create_table :#{table_name}#{primary_key_option} do |t|"]
       lines.concat(key_column_lines)
@@ -58,7 +67,7 @@ module Grain
     def primary_key_option
       return ", id: :bigint" if surrogate_key?
 
-      ", primary_key: #{schema.primary_key.inspect}"
+      ", primary_key: #{symbol_list(schema.primary_key)}"
     end
 
     def key_column_lines
@@ -80,7 +89,7 @@ module Grain
     def uniqueness_index
       return nil unless surrogate_key?
 
-      "add_index :#{table_name}, #{schema.key_columns.inspect}, unique: true,\n" \
+      "add_index :#{table_name}, #{symbol_list(schema.key_columns)}, unique: true,\n" \
         "          nulls_not_distinct: true, name: #{uniqueness_index_name.inspect}"
     end
 

data/lib/grain/path.rb

@@ -26,6 +26,22 @@ module Grain
       new(hops, column)
     end
 
+    # A path with no terminal column: just the associations a measure's expression
+    # needs joined in, so it can read their columns.
+    #
+    #   parse_association(:match)          # hops [:match]
+    #   parse_association(order: :store)   # hops [:order, :store]
+    def self.parse_association(through)
+      case through
+      when Symbol, String then new([through], nil)
+      when Hash
+        hops, column = walk(through, [])
+        new(hops + [column], nil)
+      else
+        raise InvalidDefinitionError, "through takes an association name or a nested hash, got #{through.inspect}"
+      end
+    end
+
     def self.walk(via, hops)
       case via
       when Symbol, String then [hops, via.to_sym]
@@ -50,7 +66,7 @@ module Grain
 
     def initialize(hops, column)
       @hops = hops.map(&:to_sym).freeze
-      @column = column.to_sym
+      @column = column&.to_sym
       validate!
       freeze
     end
@@ -66,7 +82,7 @@ module Grain
     end
 
     def to_s
-      (hops + [column]).join(".")
+      (hops + [column]).compact.join(".")
     end
 
     def inspect

data/lib/grain/query.rb

@@ -13,12 +13,13 @@ module Grain
   class Query
     attr_reader :rollup, :definition
 
-    def initialize(rollup, filters: {}, range: nil, groups: {})
+    def initialize(rollup, filters: {}, range: nil, groups: {}, across_tenants: false)
       @rollup = rollup
       @definition = rollup.definition.validate!
       @filters = filters
       @range = range
       @groups = groups
+      @across_tenants = across_tenants
     end
 
     # Filters on any dimension. A value may be an id, an ActiveRecord object, an
@@ -46,7 +47,15 @@ module Grain
       merge(groups: @groups.merge(groups))
     end
 
+    # Reads every tenant at once, which is a real thing to want — a platform-wide
+    # total, an admin dashboard — and has to be asked for by name. The dangerous
+    # read is the one nobody can see in the code.
+    def across_tenants
+      merge(across_tenants: true)
+    end
+
     def sql
+      require_tenant!
       QuerySql.new(definition, filters: @filters, range: @range, groups: @groups).to_s
     end
 
@@ -82,7 +91,15 @@ module Grain
     private
 
     def merge(**changes)
-      self.class.new(rollup, filters: @filters, range: @range, groups: @groups, **changes)
+      self.class.new(rollup,
+                     filters: @filters, range: @range, groups: @groups,
+                     across_tenants: @across_tenants, **changes)
+    end
+
+    # Checked where the statement is built rather than left to the caller: the
+    # mistake this catches produces a plausible number, not an error.
+    def require_tenant!
+      TenantGuard.new(rollup, @filters).check! unless @across_tenants
     end
 
     def readable?(name)

data/lib/grain/query_sql.rb

@@ -62,11 +62,35 @@ module Grain
       column = quote_column(name)
       case value
       when nil then "#{column} IS NULL"
-      when Array then "#{column} IN (#{value.map { |item| quote(item) }.join(", ")})"
+      when Array then any_of(column, value)
       else "#{column} = #{quote(value)}"
       end
     end
 
+    # A list is a set of coordinates to match, and a null is one of them: the
+    # cells with no value for a dimension are the ones a dashboard shows as
+    # "uncategorised". IN would treat that null as an unknown rather than a
+    # coordinate, so those cells would drop out of the answer without a word.
+    #
+    # An empty list is not a mistake either — it is `current_user.churches.ids`
+    # coming back empty — and it means nothing matches. `IN ()` is not valid SQL,
+    # so before this it raised a syntax error from inside a dashboard.
+    # empty? rather than any?: [nil].any? is false, and so is [false].any?, so
+    # asking whether there is anything in a list of values by truthiness drops
+    # exactly the values this method exists to handle.
+    def any_of(column, values)
+      nulls, present = values.partition(&:nil?)
+      parts = []
+      parts << "#{column} IN (#{present.map { |item| quote(item) }.join(", ")})" unless present.empty?
+      parts << "#{column} IS NULL" unless nulls.empty?
+
+      case parts.length
+      when 0 then "FALSE"
+      when 1 then parts.first
+      else "(#{parts.join(" OR ")})"
+      end
+    end
+
     def range_condition
       return nil if @range.nil?
 

data/lib/grain/railtie.rb

@@ -3,19 +3,22 @@
 require "rails/railtie"
 
 module Grain
-  # Hooks Grain into a Rails application: rake tasks, autoloading of
-  # app/rollups, and the default logger.
+  # Hooks Grain into a Rails application.
+  #
+  # Nothing here touches autoload_paths. Rails already autoloads and eager loads
+  # every directory under app/, so app/rollups needs no help — and by the time a
+  # railtie initializer runs, autoload_paths is frozen anyway.
   class Railtie < ::Rails::Railtie
     initializer "grain.logger" do
       Grain.config.logger ||= Rails.logger
     end
 
-    rake_tasks do
-      load File.expand_path("../tasks/grain.rake", __dir__)
+    initializer "grain.drain_job" do
+      ActiveSupport.on_load(:active_job) { require "grain/drain_job" }
     end
 
-    initializer "grain.autoload_rollups" do |app|
-      app.config.autoload_paths << app.root.join("app/rollups") if app.root.join("app/rollups").exist?
+    rake_tasks do
+      load File.expand_path("../tasks/grain.rake", __dir__)
     end
   end
 end

data/lib/grain/registry.rb

@@ -48,10 +48,18 @@ module Grain
         Rollup.subclasses.select { |rollup| rollup.name && valid?(rollup) }
       end
 
+      # Constantized rather than required, so the autoloader stays in charge.
+      # Requiring a file Zeitwerk manages either double-defines the class or fails
+      # outright, and in development nothing has referenced these yet.
       def eager_load_rollups
         return unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
 
-        Dir[Rails.root.join("app/rollups/**/*.rb")].sort.each { |path| require path }
+        directory = Rails.root.join("app/rollups")
+        return unless directory.exist?
+
+        Dir[directory.join("**/*.rb")].sort.each do |path|
+          path.delete_prefix("#{directory}/").delete_suffix(".rb").camelize.safe_constantize
+        end
       end
 
       # A rollup that cannot be used is left out rather than allowed to take the
@@ -76,8 +84,12 @@ module Grain
         rollup.definition.fact.model.table_name
       end
 
+      # Both the tables dimensions are resolved through and the tables measures
+      # read from. Missing the second set is a silent failure: the trigger fires,
+      # the log takes the row, and nothing routes it to a rollup that cares.
       def watched_tables(rollup)
-        WatchedColumns.new(rollup.definition).to_h.keys
+        columns = WatchedColumns.new(rollup.definition)
+        columns.to_h.keys + columns.unnarrowable_tables
       end
     end
   end

data/lib/grain/rollup.rb

@@ -74,6 +74,12 @@ module Grain
         query.by(*names, **coarse)
       end
 
+      # Lifts the tenant requirement for a read that is meant to span every one
+      # of them. Reads are keyed by tenant and refuse to run without it.
+      def across_tenants
+        query.across_tenants
+      end
+
       # Populates the rollup from data that already exists. A new rollup is empty
       # until this runs: its triggers only see what happens next.
       def backfill(from: nil, pause: 0, &progress)

data/lib/grain/tenant_guard.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Grain
+  # Refuses a read that does not say which tenant it is for.
+  #
+  # Every rollup is keyed by a tenant, so leaving it out does not make a number
+  # slightly wrong, it makes it somebody else's: the read totals every tenant at
+  # once and nothing about the result looks unusual. Grain cannot pick a default,
+  # since it has no idea whose data the caller is entitled to, so the only two
+  # options are to raise or to leak.
+  class TenantGuard
+    attr_reader :rollup, :filters
+
+    def initialize(rollup, filters)
+      @rollup = rollup
+      @filters = filters
+    end
+
+    def check!
+      name = rollup.definition.tenant.name
+      return if filters.key?(name) && !filters[name].nil?
+
+      raise MissingTenantError, complaint(name)
+    end
+
+    private
+
+    def complaint(name)
+      return null_tenant(name) if filters.key?(name)
+
+      "#{rollup} is keyed by #{name} and was read without it, which would total every tenant " \
+        "at once. Narrow it with .for(#{name}: ...), or ask for .across_tenants explicitly."
+    end
+
+    # A tenant column is never nullable, so a null filter matches no cell at all
+    # and the read comes back a clean zero — a lie about the data rather than a
+    # leak, and just as quiet.
+    def null_tenant(name)
+      "#{rollup} was read with #{name}: nil. A tenant is never null, so this matches no cell " \
+        "and reads as zero; pass a real #{name}, or .across_tenants to span all of them."
+    end
+  end
+end

data/lib/grain/triggers.rb

@@ -28,9 +28,9 @@ module Grain
       @definitions = Array(definitions).map(&:validate!).uniq
     end
 
-    # Fact tables first, then the tables reached through them.
+    # The tables that cannot be narrowed first, then the ones that can.
     def specs
-      fact_specs + related_specs
+      unnarrowed_specs + related_specs
     end
 
     # One statement per entry, so a migration can execute them individually
@@ -53,20 +53,23 @@ module Grain
 
     private
 
-    # Measures aggregate arbitrary SQL, so which of a fact table's columns feed
-    # them cannot be known. Narrowing here risks missing an update and letting a
-    # rollup drift, so every update on a fact table is logged. Being a fact for
-    # any one rollup is enough to disqualify the table from narrowing.
-    def fact_specs
-      fact_tables.map { |table| Spec.new(table: table, update_columns: nil) }
+    # Measures aggregate arbitrary SQL, so which columns feed them cannot be known
+    # — not on the fact table, and not on any table a measure reads through. Both
+    # therefore log every update: narrowing would risk missing one and letting a
+    # rollup drift in silence. Being unnarrowable for any single rollup is enough
+    # to disqualify a table for all of them.
+    def unnarrowed_specs
+      unnarrowed_tables.map { |table| Spec.new(table: table, update_columns: nil) }
     end
 
-    def fact_tables
-      definitions.map { |definition| TypeResolver.new(definition).fact_table }.uniq
+    def unnarrowed_tables
+      definitions.flat_map do |definition|
+        [TypeResolver.new(definition).fact_table] + WatchedColumns.new(definition).unnarrowable_tables
+      end.uniq
     end
 
     def related_specs
-      union_of_related_columns.reject { |table, _| fact_tables.include?(table) }
+      union_of_related_columns.reject { |table, _| unnarrowed_tables.include?(table) }
                               .map { |table, columns| Spec.new(table: table, update_columns: columns.sort) }
     end
 

data/lib/grain/type_resolver.rb

@@ -12,6 +12,12 @@ module Grain
     # the row falls into, so its type comes from the grain rather than the source.
     BUCKET_TYPES = { day: :date }.freeze
 
+    # ActiveRecord reports a bigint column as :integer carrying a limit of 8, so
+    # taking its type at face value would key a rollup on four bytes while the
+    # source uses eight. That holds until an id passes two billion and then stops,
+    # silently, on a table nobody thinks to look at.
+    INTEGER_WIDTHS = { 8 => :bigint, 2 => :integer, 1 => :integer }.freeze
+
     attr_reader :definition
 
     def initialize(definition)
@@ -21,7 +27,7 @@ module Grain
     def dimension_type(dimension)
       return BUCKET_TYPES.fetch(dimension.grain) if dimension.time?
 
-      source_column(dimension).type
+      widen(source_column(dimension))
     end
 
     # The type of the column a dimension is read from, before any bucketing. A
@@ -33,9 +39,12 @@ module Grain
 
     # Whether the source column can be null, which decides whether the rollup can
     # use a plain composite primary key: Postgres will not accept a null in one.
+    #
+    # A time dimension is not exempt. It stores a bucket rather than the source
+    # timestamp, but the bucket of a null timestamp is null, and declaring that
+    # column NOT NULL inside the primary key makes the first such row fail to
+    # insert — on the fact table, at write time, far from anything about Grain.
     def dimension_nullable?(dimension)
-      return false if dimension.time?
-
       source_column(dimension).null
     end
 
@@ -68,6 +77,12 @@ module Grain
         "value per dimension, or it would be counted in several cells at once."
     end
 
+    def widen(column)
+      return column.type unless column.type == :integer && column.limit == 8
+
+      INTEGER_WIDTHS.fetch(column.limit, :integer)
+    end
+
     def source_column(dimension)
       model = walk(definition.fact.model, dimension.path)
       model.columns_hash.fetch(dimension.path.column.to_s) do

data/lib/grain/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Grain
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

data/lib/grain/watched_columns.rb

@@ -28,8 +28,23 @@ module Grain
       collected
     end
 
+    # Tables a measure's expression reads from, which cannot be narrowed at all.
+    #
+    # Same reasoning as the fact table: the expression is arbitrary SQL and there
+    # is no way to know which of its columns feed the measure. Guessing risks
+    # missing an update and drifting in silence, so every update is logged.
+    def unnarrowable_tables
+      definition.measure_paths.flat_map { |path| tables_along(path) }.uniq
+    end
+
     private
 
+    def tables_along(path)
+      model = definition.fact.model
+      path.hops.map { |hop| model = resolver.reflection!(model, hop, path).klass }
+          .map(&:table_name)
+    end
+
     def add_path(path, into)
       path.hops.each_with_index.reduce(definition.fact.model) do |model, (hop, index)|
         add_hop(model, hop, path, index, into)

data/lib/grain.rb

@@ -21,10 +21,12 @@ require_relative "grain/migration"
 require_relative "grain/watched_columns"
 require_relative "grain/triggers"
 require_relative "grain/registry"
+require_relative "grain/installer"
 require_relative "grain/join_graph"
 require_relative "grain/projection"
 require_relative "grain/cells"
 require_relative "grain/recompute"
+require_relative "grain/tenant_guard"
 require_relative "grain/query_sql"
 require_relative "grain/query"
 require_relative "grain/backfill"

data/lib/tasks/grain.rake

@@ -12,6 +12,16 @@ namespace :grain do
     abort("grain:verify found disagreements") if reports.any? { |report| !report.clean? } && !repair
   end
 
+  desc "Re-attach the trigger function and every trigger. Needed after a schema load."
+  task triggers: :environment do
+    tables = Grain::Installer.install!
+    if tables.empty?
+      puts "grain: no rollups found, nothing to attach"
+    else
+      puts "grain: triggers attached to #{tables.join(", ")}"
+    end
+  end
+
   desc "Populate a rollup from data that already exists. ROLLUP=Name [FROM=2026-08-01] [PAUSE=0.5]"
   task backfill: :environment do
     name = ENV.fetch("ROLLUP") { abort("grain:backfill needs ROLLUP=SomeRollup") }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grain
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Oscar Ortega
@@ -38,10 +38,10 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '7.1'
 description: |-
-  Grain keeps dashboard aggregates pre-computed and incrementally up to date
-  inside your own Postgres database. You declare the grain of an aggregate
-  once — tenant, time bucket and dimensions — and Grain maintains it with
-  deltas driven by database triggers instead of recomputing everything on a
+  Grain keeps dashboard aggregates pre-computed and up to date inside your own
+  Postgres database. You declare the grain of an aggregate once — tenant, time
+  bucket and dimensions — and database triggers record what changed so a worker
+  can rebuild just the affected cells, instead of recomputing everything on a
   schedule. No new infrastructure, no materialized view refresh storms, and a
   verify command that proves the aggregate still matches its source.
 email:
@@ -51,6 +51,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
@@ -71,8 +72,10 @@ files:
 - lib/grain/definition_validator.rb
 - lib/grain/dimension.rb
 - lib/grain/discrepancy.rb
+- lib/grain/drain_job.rb
 - lib/grain/errors.rb
 - lib/grain/fact.rb
+- lib/grain/installer.rb
 - lib/grain/join_graph.rb
 - lib/grain/measure.rb
 - lib/grain/migration.rb
@@ -87,6 +90,7 @@ files:
 - lib/grain/rollup.rb
 - lib/grain/rollup_lookup.rb
 - lib/grain/schema.rb
+- lib/grain/tenant_guard.rb
 - lib/grain/triggers.rb
 - lib/grain/type_resolver.rb
 - lib/grain/verification.rb