janela 0.5.0 → 0.7.0

data/docs/decisions/034-janela-will-not-freeze-a-scope-the-host-has-not-named.md

@@ -0,0 +1,238 @@
+---
+Date: 2026-09-21
+Status: Accepted
+Related: ADR 001, ADR 002, ADR 009, ADR 014, ADR 019, ADR 021, ADR 032, ADR 033
+Triggers:
+  - scheduling a snapshot, or changing what Janela::SnapshotJob takes
+  - choosing a default for anything that decides what may be read outside a request
+  - a snapshot whose numbers disagree with the page it was published from
+  - adding a setting so a host can replace something the gem ships
+  - wondering whether the shipped snapshot job should exist at all
+Topics: snapshots, tenancy, authorisation, activejob, host-integration, security, releases
+---
+
+# ADR 034: Janela Will Not Freeze a Scope the Host Has Not Named
+
+## Context
+
+`Janela::SnapshotJob` calls `Snapshot.take` with no `on:`, so every pane
+it freezes reads the model's default scope. ADR 009 decided that
+deliberately and documented it: a relation cannot be serialised into a
+job, so "a tenanted host writes its own job around `Snapshot.take` and
+passes `on:`".
+
+Whether that is wrong depends on something Janela cannot see.
+
+**Tenancy at the model layer**, through acts_as_tenant, a `default_scope`,
+a per tenant connection or a schema. `model.all` is already the tenant's
+rows. The shipped job is correct and nothing here applies. This is what
+the multi tenancy guide's own example means when it writes
+`else model.all # acts_as_tenant has already scoped your own models`.
+
+**Tenancy at the policy layer**, through Pundit or CanCanCan. `model.all`
+is every row, and the scope the host wrote never runs.
+
+So this is not the flat bug the issue title says. It is a default that is
+right for one common architecture and silently wrong for another, chosen
+by the library where ADR 032 would have it stated by the host.
+
+### Measured
+
+The demo does not scope `Order` by tenant: its `policy_scope` filters
+Janela's own owned records and answers `model.all` for everything else,
+which makes it a model layer host for its own data. The measurement below
+was taken with that one method narrowed to what a policy layer host
+writes, `when "Order" then model.where(customer: Current.tenant)`, and
+nothing else changed.
+
+```
+live pane, signed in as one tenant:          $150.00
+snapshot the shipped job froze for them:      375.0
+that snapshot's owner column:                 that tenant
+what they are then served from the snapshot: $375.00, answered 200
+```
+
+The same application, at the same instant, shows one number on the page
+and publishes another from the row it labelled as theirs. Nothing errors
+and nothing in the log says so. ADR 032 called a pane that lies the worst
+thing this library can do, and this is that pane with a URL and a
+lifetime.
+
+### Why it is worth a decision rather than a patch
+
+**It persists, and it publishes.** A live unscoped read is wrong once, on
+a screen, to somebody already authenticated. A snapshot freezes the
+number into a row and serves it at an address. ADR 009 names the
+motivating case as "an external audience with no accounts", so the
+failure mode is frozen cross tenant data published to people outside the
+application altogether.
+
+**ADR 033 made the promise louder.** Giving `janela_snapshots` an owner
+invites a host to read the row as "this snapshot belongs to this tenant".
+The row now says so. Its contents do not have to agree, and ADR 033 said
+in as many words that adding the column sharpens this rather than
+softening it.
+
+### What a fix has to get past
+
+A relation cannot be serialised into a job. That constraint produced the
+current behaviour and has not moved.
+
+**Require `on:` on `Taking#pane`.** Makes the guess impossible, and
+supersedes ADR 009's default for every caller, including the console and
+rake callers for whom it was always right. ADR 032 explicitly left `on:`
+alone on the grounds that it is a call a maintainer writes in their own
+Ruby, where nothing is being decided on their behalf.
+
+**A serialisable way to name a scope**, such as
+`{ model: "orders", scope: "for_tenant" }`. Rejected twice over: it is a
+query language in miniature, which ADR 001 and ADR 002 both push against,
+and it is arbitrary class method invocation from queue arguments, so
+whoever can enqueue a job can call anything.
+
+**Derive the scope from the owner ADR 033 added.** Janela would have to
+know how a host's models relate to a tenant, which means interpreting the
+owner, which ADR 014 and ADR 033 both forbid.
+
+**Detect which kind of host this is.** The obvious idea, and ADR 032 is
+what kills it. After ADR 032 every host defines `policy_scope`, and a
+model layer host and a single tenant host both define it as `model.all`,
+so responding to it distinguishes nothing. There is no controller
+instance in a job to ask in any case, and no current tenant for it to
+answer about.
+
+**A setting naming the host's own job**, `Janela.snapshot_job =
+"TenantSnapshotJob"`. Rejected because it has nothing to indirect.
+Verified by reading the engine: nothing in `app/` or `lib/` enqueues
+`SnapshotJob`, there is no publish action and no create route, and ADR
+009 decided there would not be. The host's own scheduler is the only
+caller and it already names a class, so the setting would be read by
+nobody. It is the shape to reach for on the day Janela becomes the
+caller, which ADR 033 already named as the thing that would reopen all of
+this, and until then it fails the test ADR 021 and ADR 023 set for
+whether a setting has earned itself.
+
+**Remove `SnapshotJob`.** Not a straw man. ADR 009's own consequences say
+"the shipped job is deliberately naive. If most hosts turn out to write
+their own, the job should be removed rather than grown", and the
+documentation has been sending tenanted hosts to write their own since
+the day it shipped. It loses to two things. The evidence ADR 009 asked
+for does not exist: there is one demo, not a population of hosts. And
+removal costs model layer and single tenant hosts a real convenience to
+solve a problem neither of them has.
+
+**A doctor check alone.** Rejected for ADR 032's reason and one of its
+own. It is advisory, so it speaks at setup time and cannot stop a job.
+And it cannot tell the two architectures apart any better than the
+library can, so it would either stay silent or cry wolf at every host,
+which is the false alarm ADR 021 exists to prevent.
+
+## Decision
+
+**The snapshot job asks one question, `scope_for(model)`, and refuses to
+answer it on the host's behalf.**
+
+Everything above is one question wearing two costumes: what rows does
+this pane freeze? It becomes one method on the job, and the two
+architectures answer it in the two ways each can answer honestly.
+
+**A model layer or single tenant host answers in a symbol.** The shipped
+`scope_for` reads a `scope:` argument and has no default:
+
+```ruby
+Janela::SnapshotJob.perform_later(name: "September 2026", owner: account,
+                                  scope: :model_default,
+                                  panes: [ { "model" => "orders", "measure" => "revenue" } ])
+```
+
+`:model_default` says each pane is taken over its model's default scope,
+and that this is the host's claim rather than Janela's guess. It is the
+same move as `private def policy_scope(model) = model.all`: not
+ceremony, a sentence somebody should have to write rather than inherit.
+Absent, `scope_for` raises `Janela::Unscoped`, the same class and the
+same word as ADR 032, because it is the same refusal in the other half
+of the library. A value Janela does not know raises `ArgumentError`,
+plainly, because a job's `perform` is a method call and not a request.
+
+**A policy layer host answers in Ruby, by subclassing.** A relation
+cannot cross the queue, but a class name can, and the host's scheduler
+already names one:
+
+```ruby
+class TenantSnapshotJob < Janela::SnapshotJob
+  private def scope_for(model) = model.where(account: owner)
+end
+```
+
+They schedule that instead, and pass no `scope:`, because the method that
+reads it is the one they replaced. `Janela::SnapshotJob` is a documented
+base class rather than a leaf, and the serialisable `panes:` list, which
+is the only genuinely reusable part of it and the part a host would
+otherwise copy, keeps working. `perform` records what it was told and
+exposes `owner`, `name` and `filters` as private readers, so a subclass
+never has to override `perform` or reach into ActiveJob's `arguments`.
+
+**This is a hook, and ADR 032 is why it is allowed to be one.** A
+`scope_for` whose unanswered case returns `model.all` is exactly the
+shape ADR 032 removed, and was rejected on that ground while the keyword
+was a separate idea. Folding the two together inverts it: the default is
+not the widest scope, it is a refusal. A host who has never heard of
+`scope_for` does not get somebody else's numbers, they get an exception
+naming both ways to answer.
+
+**One question, so one place to answer it.** A symbol and a subclass are
+not two competing APIs in ADR 001's sense. They are the same method,
+answered by a caller who has nothing to add and by a caller who does.
+
+**`Snapshot.take` and `Taking#pane` are untouched.** `on:` keeps
+defaulting to `model.all`. ADR 032 drew that seam and it holds: the line
+is between what Janela chooses inside its own code and what a host asks
+for directly, and `take` is the host's own Ruby.
+
+**No new doctor check.** A check earns itself by catching something quiet
+(ADR 021), and after this there is nothing quiet left to catch: the job
+either was answered or it raises. That is the opposite of the
+`snapshots-nobody-will-see` case, where the failure was a row that simply
+sat there.
+
+**ADR 009 is narrowed, not superseded.** Everything it decided about what
+a snapshot stores, how a stored pane is addressed and what static mode is
+stands. Two sentences change. "The shipped job uses each model's default
+scope" becomes "when told to", and "removed rather than grown" is
+answered: it grows by one overridable method, which is how Rails ships a
+default a host can replace.
+
+## Consequences
+
+- A policy layer host's instruction stops being "write your own job" and
+  becomes "override one method", which is a sentence the multi tenancy
+  guide can end its rough edge section with instead of a link to an
+  issue.
+- **Breaking, by one keyword**, so it goes in a minor release with an
+  `UPGRADING.md` section and a `post_install_message` (ADR 015).
+- **A job already on the queue at upgrade time was serialised without
+  `scope:` and will raise when it performs.** A deployment hazard rather
+  than a code change, invisible from the diff, and it belongs in the
+  upgrade note beside the keyword: drain or re-enqueue before deploying,
+  or expect the retries.
+- **`SnapshotJob`'s insides become public surface.** `scope_for` and the
+  readers beside it are a host's to override, so changing the shape of
+  the `panes:` loop is a breaking change from here on, where today it is
+  an internal detail. That is the real price of a base class over a leaf,
+  and it is paid knowingly: the surface is one method and three readers,
+  which is small enough to keep legible and small enough to fork past.
+- The job stays naive on purpose. It does not become the place where
+  scoping is solved. It becomes the place where the host says who is
+  solving it.
+- The guide's "what is still rough" section and the README's paragraph on
+  the job both change in the same commit that lands the code.
+- A host who writes `scope: :model_default` without reading what it means
+  is no better off than before. True of ADR 032's one line too. The claim
+  is not that a keyword teaches, it is that a library should not make
+  this particular claim on a host's behalf.
+- What would change this decision: Janela growing a caller of its own, a
+  publish button or a scheduled frame, at which point the class to
+  enqueue is Janela's question rather than the scheduler's and a setting
+  earns itself for the first time. ADR 033 named that same event as the
+  one that would reopen how a snapshot learns its owner, so the two
+  should be read together when it happens.

data/docs/decisions/INDEX.md

@@ -24,21 +24,21 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | **Open-source & host-decoupling** | 001, 022 |
 | **DSL & query layer** | 002, 006, 007, 020, 025 |
 | **Dependencies** | 002, 003, 004, 006, 017, 025 |
-| **Authorisation** | 002, 003, 004, 009, 017, 019, 022 |
+| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034 |
 | **Performance & storage** | 007, 017, 025 |
 | **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025 |
 | **Layouts & views** | 011, 012, 016, 018, 020, 027 |
 | **CSS & styling** | 016, 018, 023, 026, 027 |
-| **Frames, panes & persistence** | 012, 013, 014, 019 |
+| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033 |
 | **Naming rule** | 014, 023 |
 | **JavaScript delivery & charts** | 004, 006, 026 |
 | **Time dimensions** | 006, 025 |
 | **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025 |
-| **Snapshots & publishing** | 009, 020, 028 |
+| **Snapshots & publishing** | 009, 020, 028, 033, 034 |
 | **AI agents & guidance** | 010, 015, 021 |
-| **Releases & upgrades** | 015, 021 |
+| **Releases & upgrades** | 015, 021, 032, 034 |
 | **Accessibility & keyboard** | 024 |
-| **Security** | 003, 025, 028 |
+| **Security** | 003, 025, 028, 031, 032, 034 |
 | **Testing** | 003 |
 
 ## Chronological
@@ -73,7 +73,13 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 026 | A Renderer Is the Seam, and HTML Comes First | 2026-09-18 | Accepted |
 | 027 | The Gallery Is a Host Page, Built from the Gem's Helpers | 2026-09-18 | Accepted |
 | 028 | The Predicate List ADR 025 Named Was Not Quite Right | 2026-09-18 | Accepted |
+| 029 | A Pane's Frame Is Identified by Who It Is, Not by What It Shows | 2026-09-18 | Accepted |
+| 030 | A Pane's src Belongs to Turbo, So a Host Talks to the Frame | 2026-09-18 | Accepted |
+| 031 | A Subclass Inherits the Dashboard Its Parent Declared | 2026-09-19 | Accepted |
+| 032 | Janela Will Not Read a Model It Cannot Scope | 2026-09-20 | Accepted |
+| 033 | A Snapshot Is Told Who Owns It | 2026-09-21 | Accepted |
+| 034 | Janela Will Not Freeze a Scope the Host Has Not Named | 2026-09-21 | Accepted |
 
 ## Next number
 
-Next ADR: 029
+Next ADR: 035

data/docs/multi-tenancy.md

@@ -6,15 +6,22 @@ engine asks your application two questions and does what it is told.
 
 | Question | How your application answers | If it says nothing |
 | --- | --- | --- |
-| What may this request read? | `policy_scope(model)` on the controller Janela inherits | Everything: `model.all` |
+| What may this request read? | `policy_scope(model)` on the controller Janela inherits | Nothing: it raises `Janela::Unscoped` |
 | What owns a frame being created? | `janela_frame_owner` on the same controller | Nothing: a nil owner |
+| What owns a snapshot being taken? | `owner:`, an argument to `Snapshot.take` | Nothing: a nil owner |
+| What rows does a scheduled snapshot freeze? | `scope:` on `SnapshotJob`, or `scope_for` in a subclass of it | Nothing: it raises `Janela::Unscoped` |
 
-Both are ordinary methods on your `ApplicationController`, found by
-duck typing. Pundit defines the first for you. Anything else, you
-define in about five lines. ADR 019 has the reasoning for asking
+The first two are ordinary methods on your `ApplicationController`,
+found by duck typing. Pundit defines the first for you. Anything else,
+you define in about five lines. ADR 019 has the reasoning for asking
 rather than being configured: ownership is per-request state, and a
 setting cannot hold it.
 
+The third is an argument rather than a method for the reason ADR 033
+gives: a snapshot is never taken in a request. It is taken in a job, a
+task or a console, where there is no controller to ask and no current
+tenant to ask about, so the caller passes what it already knows.
+
 ## What goes through your scope
 
 Everything. There is no path through the engine that reads a record
@@ -104,9 +111,28 @@ class and returns a relation is the whole contract.
 
 ## With one tenant
 
-Define nothing. `policy_scope` is absent, every query runs over
-`model.all`, and a frame is created with a nil owner because nothing
-is filtering on one.
+Write the answer anyway, once:
+
+```ruby
+class ApplicationController < ActionController::Base
+  private
+    def policy_scope(model) = model.all
+end
+```
+
+Janela will not guess this one. Every other question here takes silence
+as an answer, because the silent answer is the narrow one: no owner, no
+theme, no tenancy. This question's permissive answer is the widest thing
+a library can assume, so it is the one you have to say out loud (ADR
+032).
+
+The line is not ceremony either. It asserts that everyone who can reach
+a dashboard may read every row behind it, and "one tenant" and "no rows
+worth hiding from staff" are not the same claim. If the second is not
+true here, return something narrower.
+
+A frame is still created with a nil owner, because nothing is filtering
+on one.
 
 ## What owns a frame
 
@@ -123,20 +149,63 @@ save failed silently. `bin/rails janela:doctor` reports this for you:
 it asks your policy for a scope over frames and looks for an owner in
 what comes back.
 
-## Snapshots are the rough edge
+## Snapshots
+
+A snapshot carries the same polymorphic owner a frame does, so your
+policy has the same column to filter on. You pass it when you take one:
+
+```ruby
+Janela::Snapshot.take(name: "September 2026", owner: ActsAsTenant.current_tenant) do |take|
+  take.pane Order, :revenue, on: policy_scope(Order)
+end
+```
+
+```ruby
+def policy_scope(model)
+  case model.name
+  when "Janela::Frame", "Janela::Snapshot" then model.where(owner: ActsAsTenant.current_tenant)
+  else model.all
+  end
+end
+```
+
+`Janela::SnapshotJob` takes `owner:` as well, since ActiveJob carries a
+record across the queue through its GlobalID.
+
+## What a scheduled snapshot freezes
+
+The owner says who a snapshot belongs to. What the numbers inside it
+cover is a separate question, and the job asks you rather than guessing.
 
-`janela_snapshots` has no owner column. A snapshot is a name, an
-instant, the filters it was taken under and the results. So a multi
-tenant application has to scope it by something else:
+A model's default scope is already your tenant's rows if your tenancy is
+enforced on the models, through acts_as_tenant, a `default_scope`, a
+connection or a schema. Say so:
+
+```ruby
+Janela::SnapshotJob.perform_later(name: "September 2026", owner: tenant,
+                                  scope: :model_default, panes: [ ... ])
+```
+
+If your scoping lives in your policies, `model.all` is every row, and no
+symbol can carry the relation you want across a queue. Answer in Ruby.
+Subclass the job, override its one question, and schedule yours:
+
+```ruby
+class TenantSnapshotJob < Janela::SnapshotJob
+  private def scope_for(model) = model.where(account: owner)
+end
+```
 
-- Keep snapshots to one tenant, or to whoever publishes.
-- Add your own column with a migration on `janela_snapshots` and scope
-  on that.
-- Encode the tenant in the filters a snapshot is taken under, and
-  scope on the stored name.
+`name`, `owner` and `filters` are readable inside `scope_for`, so a
+subclass never has to override `perform` or read ActiveJob's arguments.
+Override `scope_for` and the `scope:` argument is not consulted: the
+method that reads it is the one you replaced.
 
-None of those is as clean as a frame's owner. Giving a snapshot the
-same polymorphic owner is [issue #32](https://github.com/retail-tasker/janela/issues/32).
+Answer neither way and the job raises `Janela::Unscoped` instead of
+freezing a scope nobody chose. That matters more here than on a live
+page: a wrong pane is wrong once, on a screen, to somebody already
+signed in, while a wrong snapshot is frozen into a row, labelled with an
+owner and served at an address (ADR 034).
 
 ## Proving your wiring
 

data/lib/janela/definition.rb

@@ -6,10 +6,20 @@ module Janela
 
     attr_reader :model, :measures, :dimensions
 
-    def initialize(model)
+    def initialize(model, &block)
       @model = model
       @measures = {}
       @dimensions = {}
+      @block = block
+      instance_eval(&block) if block
+    end
+
+    # The same declaration read against another model, which is how a subclass
+    # inherits a dashboard: its measures and dimensions are its parent's, and
+    # the queries they run are its own, because ActiveRecord adds the type
+    # condition to a relation on the subclass (ADR 031).
+    def for(model)
+      self.class.new(model, &@block)
     end
 
     def measure(name, **aggregate)

data/lib/janela/doctor.rb

@@ -10,8 +10,9 @@ module Janela
     # Run in this order, and each one names the finding it produces: a host
     # silences a check by that name (ADR 021).
     CHECKS = %i[stale_identifiers unmounted_engine unmigrated_tables unregistered_controllers
-                through_dimensions_without_an_allowlist frames_nobody_will_own
-                unauthenticated_endpoints hardcoded_disallowed_predicates].freeze
+                through_dimensions_without_an_allowlist unscoped_reads frames_nobody_will_own
+                snapshots_nobody_will_see unauthenticated_endpoints
+                hardcoded_disallowed_predicates].freeze
 
     # Identifiers a previous version of Janela used, and what replaced them.
     RENAMED = {
@@ -181,6 +182,28 @@ module Janela
         end
       end
 
+      # A host that has defined no policy_scope has not said what may be read,
+      # and since ADR 032 every dashboard raises rather than answering with
+      # every row. Reported so it is found here rather than by a visitor.
+      #
+      # Where unauthenticated_endpoints has to hedge, because what counts as
+      # authentication cannot be determined by reading, this one is exact: the
+      # method is defined or it is not, and that is the whole contract.
+      def unscoped_reads
+        parent = Janela.parent_controller.safe_constantize
+        return unless parent
+        return if parent.private_method_defined?(:policy_scope) || parent.method_defined?(:policy_scope)
+
+        Finding.new(severity: :error,
+          summary: "#{parent} defines no policy_scope, so every pane will raise",
+          detail: "  Janela asks your controller what may be read and refuses to guess.\n" \
+                  "  Define it on #{parent}:\n" \
+                  "    private def policy_scope(model) = model.all\n" \
+                  "  That line says every visitor may read every row of every model on a\n" \
+                  "  dashboard. If that is not true of this application, return something\n" \
+                  "  narrower; docs/multi-tenancy.md has the wiring for the usual libraries.")
+      end
+
       # A host whose policy filters frames by owner, but which never tells
       # Janela what owns a new one, creates frames its own scope then hides.
       # The failure is silent, and a typo in the method name looks the same as
@@ -189,7 +212,7 @@ module Janela
         parent = Janela.parent_controller.safe_constantize
         return unless parent&.private_method_defined?(:policy_scope) || parent&.method_defined?(:policy_scope)
         return if parent.private_method_defined?(:janela_frame_owner) || parent.method_defined?(:janela_frame_owner)
-        return unless Janela::Frame.table_exists? && scope_filters_frames_by_owner?(parent)
+        return unless Janela::Frame.table_exists? && scope_filters_by_owner?(parent, Janela::Frame)
 
         Finding.new(severity: :error,
           summary: "#{parent} scopes frames by owner but defines no janela_frame_owner",
@@ -202,11 +225,39 @@ module Janela
         nil # no database or no policy to ask; nothing can be concluded
       end
 
+      # A snapshot with no owner is stored and unreachable to a policy that
+      # filters on one: the row is there, a link to it is a 404, and nothing
+      # says why. Most often these were taken before the column existed, which
+      # is what an upgrade produces.
+      #
+      # ADR 033 judged this a thinner case than the frame's, because a caller
+      # assigns a snapshot's owner in its own Ruby rather than the engine doing
+      # it silently, and said it was worth revisiting if it bit. It bit four
+      # times in this repository's tests and once on the live demo within an
+      # afternoon of the column landing (#49).
+      def snapshots_nobody_will_see
+        parent = Janela.parent_controller.safe_constantize
+        return unless parent && Janela::Snapshot.table_exists?
+        return unless scope_filters_by_owner?(parent, Janela::Snapshot)
+
+        unowned = Janela::Snapshot.where(owner_id: nil).count
+        return if unowned.zero?
+
+        Finding.new(severity: :warning,
+          summary: "#{unowned} #{'snapshot'.pluralize(unowned)} with no owner, which your policy filters on",
+          detail: "  Your policy narrows snapshots by owner, so one with none is stored and\n" \
+                  "  unreachable: a link to it answers 404 and nothing says why. Usually these\n" \
+                  "  were taken before the owner column existed. Assign an owner to them, or\n" \
+                  "  delete them, and pass owner: to Janela::Snapshot.take from now on.")
+      rescue StandardError
+        nil # no database or no policy to ask; nothing can be concluded
+      end
+
       # Asking the policy rather than reading its source: a scope that narrows
-      # frames is one that will hide an unowned one.
-      def scope_filters_frames_by_owner?(parent)
-        scope = parent.allocate.send(:policy_scope, Janela::Frame)
-        scope.to_sql.include?("owner")
+      # an owned record is one that will hide an unowned one. Shared, because
+      # a frame and a snapshot are the same question asked of two tables.
+      def scope_filters_by_owner?(parent, model)
+        parent.allocate.send(:policy_scope, model).to_sql.include?("owner")
       rescue StandardError
         false
       end

data/lib/janela/model.rb

@@ -1,25 +1,61 @@
 module Janela
   module Model
+    # Dimensions are the only things Janela filters on, so they are the
+    # Ransack allowlist. This asks for the definition when it is called rather
+    # than closing over one, so a subclass answers with the definition it
+    # reports, whether that is its parent's or one it declared itself. The two
+    # halves cannot then disagree, which is what they did before ADR 031: a
+    # subclass inherited this list and reported no definition behind it.
+    module RansackAllowlist
+      def ransackable_attributes(_auth_object = nil)
+        janela.ransackable_attributes
+      end
+
+      def ransackable_associations(_auth_object = nil)
+        janela.ransackable_associations
+      end
+    end
+
     def janela(&block)
-      return @janela_definition unless block
+      return @janela_definition ||= inherited_janela_definition unless block
 
-      @janela_definition = Definition.new(self)
-      @janela_definition.instance_eval(&block)
+      @janela_definition = Definition.new(self, &block)
       define_janela_ransack_allowlist
       Janela.register(self)
       @janela_definition
     end
 
+    # A subclass cannot be registered where its parent declares, because it
+    # does not exist yet, so it registers as it is created (ADR 031). An
+    # anonymous class has no route key to be addressed by; naming it is the
+    # host's move and declaring on it is the host's other one.
+    def inherited(subclass)
+      super
+      Janela.register_subclass(subclass) if subclass.name && janela
+    end
+
     private
-      # Dimensions are the only things Janela filters on, so they are the
-      # Ransack allowlist. A model that already declares its own allowlist
-      # keeps it.
+      # What a subclass inherits is the declaration, not the definition
+      # object. A definition holds the model it queries, so a subclass handed
+      # its parent's would report the right dashboard and then total the
+      # parent's rows behind it.
+      def inherited_janela_definition
+        superclass.janela&.for(self) if superclass.respond_to?(:janela)
+      end
+
+      # A model that already answers for itself keeps its answer, whether it
+      # said so here or on a class above. Ransack's own default lives on
+      # ActiveRecord::Base, so anything nearer than that was somebody's
+      # decision and is not ours to replace.
       def define_janela_ransack_allowlist
-        return if singleton_class.method_defined?(:ransackable_attributes, false)
+        return if janela_ransack_allowlist_answered?
+
+        extend RansackAllowlist
+      end
 
-        definition = @janela_definition
-        define_singleton_method(:ransackable_attributes) { |_auth_object = nil| definition.ransackable_attributes }
-        define_singleton_method(:ransackable_associations) { |_auth_object = nil| definition.ransackable_associations }
+      def janela_ransack_allowlist_answered?
+        owner = singleton_class.instance_method(:ransackable_attributes).owner
+        !ActiveRecord::Base.singleton_class.ancestors.include?(owner)
       end
   end
 end

data/lib/janela/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Janela
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end