janela 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fd31f19d1b100c312826e8077aefc291873c0cc153410aa9c53199dcdf5ba18
-  data.tar.gz: ec551cd6c640de00e6ba13266ae2920945f68ad4a576c344e157830c9442563d
+  metadata.gz: a28af383164e7bc1176c8b41bcff4d4ee384bbdaac7313b66a781c5c047a4fb8
+  data.tar.gz: 7611b5e28e04d9dc3cf45a940eba1aae33e2b80beb708f3a24b7ecc12a650819
 SHA512:
-  metadata.gz: 692add30c86d3633d3144b6fe1fbb138246762e974f618430db2f290f1980a91bb55441104b2a1d183e67e6e16ca3ffd75aaab8d8e0156d77444950bc388dc21
-  data.tar.gz: 794ac1f1352ee3e30357d8ef2ff7bd2d0692895f932b3aec5d3acc5df55ab21e592397f111df855a120c547eea271273807e870d988a602a49c6575987ddaa9a
+  metadata.gz: 8b32263ebc50a9d33ca95a9629bde4a58937370ea70df0fe17c58d651a0f87953aeb668dc363933c0aaa5e36a2b4bd663ffbdf4ea670cf5eec3dd5e3f7ee380d
+  data.tar.gz: 7651430b673d289b5bfa1a650c66351d580714c542cba06ec046cac4236dde21079c5debeddc9d27439442596b8a317aa60adccda1d1c3c9f1216b60a0d73f54

data/CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-09-23
+
+### Added
+
+- `docs/theming.md`, "Theming Janela": the contract a theme may target. Every class the engine renders in your own pages, the three custom properties that carry `janela.css`, what a theme is expected to leave alone, and how to write one of your own. A theme is any stylesheet you name, `Janela.theme = "midnight"` resolving from your own asset paths, and vitral is one of them rather than the one. Ships in the gem; `test/dummy` has a live page at `/vitral` showing all of it against real panes (ADR 036).
+- `janela-own-headings`, a class you put on any ancestor when your own markup already says what a pane is. A table pane's `<caption>` and a single value's label stop being drawn and stay in the accessibility tree. Hidden rather than removed on purpose: a caption is the table's accessible name, so `display: none` lands a screen reader on a grid of numbers with nothing to say what they measure, which is the easy wrong answer this saves you writing. A chart pane needs nothing, since its title was only ever an `aria-label` (ADR 036, #26).
+- `docs/roadmap.md`, "Where Janela Is Going": what 1.0 means, which open issues are in it, and what is deliberately not coming. Three claims that can be checked rather than a feature count, since ADR 001 rules out a 1.0 measured against what a commercial BI tool ships: the public surface stops moving, a pane can be read, and the doctor can be trusted. It ships in the gem and renders on the demo at `/docs/roadmap`, because a reader who has to open an issue tracker to find out where a library is going has been told to do the maintainer's filing. It carries no dates on purpose, so that it can only ever be wrong about substance (ADR 037).
+
+### Changed
+
+- **Breaking.** `Janela.parent_controller=` raises when the assignment cannot take effect. The superclass of `Janela::ApplicationController` is resolved once, the first time the class loads, so naming a different controller after that did nothing at all: dashboards kept inheriting whatever was named first, and the host's authentication and `policy_scope` were not the ones it had written. Nothing said so. Set it in `config/initializers/janela.rb`, which runs before anything can load a Janela controller; `config.to_prepare` and `config.after_initialize` are both too late, and the README's own layout recipe is a `to_prepare` block that loads the controller. Naming the controller Janela already inherits is still allowed, since nothing is being asked for (ADR 035, #38).
+- **The class names only Janela's own pages use are no longer public API.** ADR 016 said "the class names are public API", which read literally promised that `janela-card`, `janela-crumb`, `janela-flash`, `janela-button`, `janela-form` and the rest of the engine's own chrome would never be renamed without an upgrade note. That was a promise made to nobody about markup only the engine renders, and it made Janela's own pages harder to change than the library they serve. They are scoped under `janela-page`, which only the engine's layout sets, so they cannot reach your pages, and they may now change in any release. Everything a host's own markup contains, the grid scale and the pane primitives, is the contract and is unchanged: `docs/theming.md` lists it (ADR 036).
+
+### Fixed
+
+- Janela believes only the definitions Janela built. `Janela::Model` is extended onto every ActiveRecord model, so `janela` is a question any of them can answer, and an application whose own model defines a class method by that name wins the collision, as Ruby says it should. Janela treated anything truthy that came back as a definition: `rails janela:doctor` raised `NoMethodError: undefined method 'dimensions' for an instance of String`, a named subclass of that model was registered so `/dashboards/<its route key>/...` resolved, and `Janela.definitions` handed out a value that was not a definition to anything iterating it, such as a form offering a choice of model. Nothing about your own method changes; Janela ignores it now instead of choking on it. A *column* named `janela` was never affected either way, because an attribute is an instance method and this is a class method (#54, found while investigating #12).
+
+- `rails janela:doctor`'s `through-dimensions-without-an-allowlist` reported once per dimension and once per class inheriting a declaration, where there is only ever one allowlist to write. Two dimensions reading through the same association produced two findings whose suggested lines contradicted each other, `%w[region]` and `%w[name]`, so pasting both kept the second and silently lost the first; an STI family produced a copy of each per subclass, since a subclass shares its parent's associations. It is now one finding per associated class, naming every column that class needs and every dimension that wants one, with a line that allows all of them. A subclass that reflects an association its parent does not still gets a finding of its own, because that is a different fix (#44).
+- `rails janela:doctor` checked whether your controller *defines* `policy_scope` rather than whether calling it works, so a Pundit host with no policy for Janela's own models got a clean report and a `Pundit::NotDefinedError` on every dashboard request. Pundit defines `policy_scope` the moment it is included, whether or not the model has a policy, so for the commonest authorisation library those are different questions. `unscoped-reads` now makes the call Janela makes, against `Janela::Frame` and `Janela::Snapshot`, and reports a raise as an error quoting your own exception, which names the policy to write. ADR 032 called this check "exact: the method is defined or it is not"; ADR 035 supersedes that. Its other claim stands: Pundit raises rather than leaking, so nothing was ever exposed (ADR 035, #51).
+- `frames-nobody-will-own` and `snapshots-nobody-will-see` never fired for any application whose `policy_scope` reaches for the signed in user, which is most of them. Both asked your policy on a controller with no request, where `session`, `params` and `current_user` are unreachable, and a blanket rescue read the resulting exception as "does not filter by owner". The checks now ask the way a request does, so those are empty rather than missing, which is an unauthenticated visitor and the right thing for a check to ask about. Expect findings that were always true and never printed (ADR 035).
+- Every check about your controller read `Janela.parent_controller`, the setting, rather than `Janela::ApplicationController.superclass`, what Janela actually inherits. When a host named a parent controller too late the two differed, and the doctor reported on a class that was not in the chain, including the sentence "Janela's controllers inherit X" about a class it does not (ADR 035, #38).
+- `hardcoded-disallowed-predicates` reported an error saying a file filters a model, having only found the dimension's name followed by a predicate somewhere under `app`, `config` or `lib`. An unrelated model's Ransack call, a comment warning against the predicate, and a key in a locale file all read the same to it, and a host was told an error about code that had nothing to do with Janela. It is now a warning, says the file *mentions* the key, and admits that it cannot tell which model a match belongs to. It also reports once per `janela` declaration rather than once per class inheriting it, so an STI family no longer multiplies the same finding (ADR 021, ADR 035, #51, part of #44).
+
+## [0.7.0] - 2026-09-22
+
+### Added
+
+- `rails janela:doctor` reports snapshots stored with no owner when your policy filters snapshots by owner, as `snapshots-nobody-will-see`, a warning naming how many. Such a snapshot is stored and unreachable: the row is there, a link to it answers 404, and nothing says why. Usually they are snapshots taken before the owner column existed, which is what an upgrade produces. ADR 033 judged a check here a thinner case than the frame's, because a caller assigns a snapshot's owner in its own Ruby, and said it was worth revisiting if it bit: it bit four times in this repository's own tests and once on the live demo within an afternoon of the column landing (#49).
+- A snapshot carries an owner, the same nullable polymorphic one a frame has, so a multi tenant application's policy has the same column to filter a snapshot on that it already has for a frame. `Janela::Snapshot.take(name:, owner:)` assigns it and `Janela::SnapshotJob` carries it across the queue through its GlobalID. Janela reads nothing from it, exactly as with a frame. It is an argument rather than a method on your controller because a snapshot is never taken in a request: there is no create route and no form, only `take` called from a job, a task or a console, where a hook reaching for the current tenant would work in a console and return nil in the job that is the point of the feature. Needs `rails janela:install:migrations` and a migrate; existing snapshots keep a nil owner and nothing breaks if you ignore it. The owner says who a snapshot belongs to and nothing about the numbers inside it, which is the separate question the `SnapshotJob` entry above answers (ADR 033, #32).
+
+### Changed
+
+- **Breaking.** `Janela::SnapshotJob` will not freeze a scope you have not named. It took every pane over the model's default scope, which ADR 009 chose deliberately because a relation cannot be serialised into a job. That is your tenant's rows if your tenancy is enforced on your models, and every row of every model if your scoping lives in your policies, and nothing reachable from a job can tell which application it is in: measured against a policy scoped host, the same application showed $150.00 on the live pane and published $375.00 from the snapshot beside it, under that tenant's own name, answered 200 with nothing in the log. A live unscoped read is wrong once, on a screen, to somebody already signed in; a snapshot freezes it into a row and serves it at an address to the external audience snapshots exist for. The job now asks one question, `scope_for(model)`, and refuses to answer it for you. A host whose tenancy is on its models, or who has one tenant, passes `scope: :model_default` and carries on. A host whose scoping is in its policies answers in Ruby, where a relation is still a relation, by subclassing the job and overriding `scope_for`, with `name`, `owner` and `filters` readable beside it so nothing has to override `perform`; that replaces the old advice to write a job around `Snapshot.take` from scratch. Neither answer raises `Janela::Unscoped`, the same refusal a request gets. `Snapshot.take` and `take.pane`'s `on:` are unchanged, because those are calls you write in your own Ruby. Note before deploying: a job already on the queue was serialised without `scope:` and will raise when it performs, which no diff will show you (ADR 034, #47).
+
+- **Breaking.** Janela refuses to read a model it has not been told how to scope. `janela_scope` asked the host's controller for `policy_scope` and fell back to `model.all` when there was none, so an application using a different authorisation library, or none at all, got every row of every model on a dashboard with nothing said: a request that should have been a refusal answered 200 carrying numbers its reader may have had no right to, and no line mentioning scope reached the log. It now raises `Janela::Unscoped`, naming the method to define and the class to define it on. An application with nothing to hide answers once, `private def policy_scope(model) = model.all`, which is a sentence worth writing rather than inheriting by omission: "one tenant" and "everyone may read every row" are not the same claim. A host using Pundit is unaffected, including one missing a policy, because Pundit already raises on that. `rails janela:doctor` reports the absence as `unscoped-reads` at error severity, and unlike `unauthenticated-endpoints` it does not have to hedge, since the method is either defined or it is not (ADR 032, #7).
+
+### Fixed
+
+- A frame rendered in a host's own page read every row when `policy_scope` was a private controller method, which is the shape `docs/multi-tenancy.md` teaches and the shape Pundit's own has. Janela asked the view whether the host had defined a scope, where its own controllers ask the controller, and a view cannot see a private controller method: the same application was scoped on Janela's pages and silently unscoped on its own, with no error and nothing in the log. A host using Pundit was unaffected, because `Pundit::Helper` separately defines a view side copy. If you embed `janela_frame` or `janela_pane` in your own views and your scope narrows what a pane counts, those numbers were too high and are now correct (#46).
+
 ## [0.6.0] - 2026-09-20
 
 ### Added
@@ -152,6 +192,8 @@ First alpha, installed from GitHub for testing in a single host application.
 - Only models that declare a `janela` block are addressable over HTTP.
 - ADRs 001 to 004 in `docs/decisions/`, shipped inside the gem.
 
+[0.8.0]: https://github.com/retail-tasker/janela/releases/tag/v0.8.0
+[0.7.0]: https://github.com/retail-tasker/janela/releases/tag/v0.7.0
 [0.6.0]: https://github.com/retail-tasker/janela/releases/tag/v0.6.0
 [0.5.0]: https://github.com/retail-tasker/janela/releases/tag/v0.5.0
 [0.4.1]: https://github.com/retail-tasker/janela/releases/tag/v0.4.1

data/README.md

@@ -27,7 +27,7 @@ Janela is an alpha on [rubygems.org](https://rubygems.org/gems/janela). It has t
 
 ```ruby
 # Gemfile
-gem "janela", "~> 0.6"
+gem "janela", "~> 0.8"
 ```
 
 ```ruby
@@ -348,13 +348,15 @@ The model is its route key (`orders`, `sales_orders`), then the measure, then op
 A snapshot freezes the results of several panes at one instant, under one set of filters, so an audience sees exactly what was signed off while the live dashboard stays editable. Results are stored, not HTML; a stored pane can still be drawn as a table or a chart. It needs the same migrations frames do.
 
 ```ruby
-Janela::Snapshot.take(name: "September 2026", filters: { status_eq: "paid" }) do |take|
+Janela::Snapshot.take(name: "September 2026", owner: Current.account, filters: { status_eq: "paid" }) do |take|
   take.pane Order, :revenue,                                on: policy_scope(Order)
   take.pane Order, :revenue, by: :status,                   on: policy_scope(Order)
   take.pane Order, :revenue, by: :placed_on, granularity: :week
 end
 ```
 
+`owner:` is optional and Janela reads nothing from it: it is there so your policy has the same column to filter a snapshot on that it has for a frame. It is an argument rather than a controller hook because a snapshot is never taken in a request, so there is nothing to ask (ADR 033).
+
 Render a stored pane the same way you render a live one:
 
 ```erb
@@ -390,7 +392,22 @@ Do not point Janela at your **application** layout. Janela is an isolated engine
 
 Stored panes are static by nature: no filter buttons, charts ignore clicks, and the URL says *as of*: `/dashboards/snapshots/42/orders/revenue/status`. Request filters are ignored because the snapshot's were fixed when it was taken.
 
-`Janela::SnapshotJob.perform_later(name:, panes: [{ "model" => "orders", "measure" => "revenue", "by" => "status" }])` takes one from serialisable arguments so you can schedule it with whatever runs your jobs. The job uses each model's default scope; if you scope by tenant, write your own job around `Snapshot.take` and pass `on:`.
+`Janela::SnapshotJob` takes one from serialisable arguments so you can schedule it with whatever runs your jobs, carrying the owner across the queue through its GlobalID. It asks you one question and will not answer it for you: what rows does each pane freeze?
+
+```ruby
+Janela::SnapshotJob.perform_later(name: "September 2026", owner: Current.account, scope: :model_default,
+                                  panes: [ { "model" => "orders", "measure" => "revenue", "by" => "status" } ])
+```
+
+`scope: :model_default` says each pane is taken over its model's default scope. That is already your tenant's rows if your tenancy is enforced on the models themselves, through acts_as_tenant, a `default_scope`, a connection or a schema. If your scoping lives in your policies instead, it is every row of every model, and no symbol can carry the relation you want, so answer in Ruby and schedule your own job:
+
+```ruby
+class TenantSnapshotJob < Janela::SnapshotJob
+  private def scope_for(model) = model.where(account: owner)
+end
+```
+
+`scope_for` is the whole extension point. Override it and the `scope:` argument is not consulted, because the method that reads it is the one you replaced; `name`, `owner` and `filters` are readable beside it, so you never have to override `perform`. Pass neither and the job raises `Janela::Unscoped` rather than freezing a scope nobody chose, which is the same refusal `policy_scope` gets in a request (ADR 034).
 
 Who may see a snapshot is your decision. Stored panes go through the same controllers as live ones, so your authentication applies; an external audience gets a page you build over `janela_snapshot_pane` behind whatever share tokens you already trust. ADR 009 has the reasoning.
 
@@ -411,9 +428,9 @@ It is *prepended* so it runs before any filter on your `ApplicationController` t
 
 Your own route helpers work in there. Janela is an isolated engine, so a bare `new_session_path` would normally resolve against Janela's routes and raise, and this bites any host code that generates a URL while inside the engine: an authentication concern, a `rescue_from` that redirects, an `after_action`. Janela forwards the route helpers it does not define itself to your application, so they behave as they do everywhere else (ADR 022). Two things to know. A name Janela also uses means Janela's in here, and `main_app.frames_path` says yours. And `url_for(@record)` resolves polymorphically with no name to forward, so that one still needs `main_app.`.
 
-Scoping is automatic when you use Pundit: `Janela::ApplicationController` calls `policy_scope(model)` if your `ApplicationController` defines it, and falls back to `model.all` otherwise. Every model you put on a dashboard needs a policy with a `Scope`, and so do `Janela::Frame` and `Janela::Snapshot`: frames, pane rows and stored panes are all read through the scope, never around it. `test/dummy/app/controllers/application_controller.rb` is the smallest honest example of the wiring.
+Scoping is automatic when you use Pundit: `Janela::ApplicationController` calls `policy_scope(model)` if your `ApplicationController` defines it, and raises `Janela::Unscoped` if it does not, rather than reading everything on the strength of an omission (ADR 032). An application with nothing to hide answers `def policy_scope(model) = model.all` once and is done; `bin/rails janela:doctor` reports the absence as `unscoped-reads` before a visitor finds it. Every model you put on a dashboard needs a policy with a `Scope`, and so do `Janela::Frame` and `Janela::Snapshot`: frames, pane rows and stored panes are all read through the scope, never around it. The doctor checks that by making the call rather than by looking for the method, because Pundit defines `policy_scope` the moment it is included and raises only when the model has no policy, so the two are different questions (ADR 035). `test/dummy/app/controllers/application_controller.rb` is the smallest honest example of the wiring.
 
-**Multi tenancy** has its own guide: [docs/multi-tenancy.md](docs/multi-tenancy.md). It covers what goes through your scope, worked wiring for Pundit, acts_as_tenant and CanCanCan, what owns a frame the analyst creates, and the one rough edge, which is that a snapshot has no owner column yet.
+**Multi tenancy** has its own guide: [docs/multi-tenancy.md](docs/multi-tenancy.md). It covers what goes through your scope, worked wiring for Pundit, acts_as_tenant and CanCanCan, what owns a frame the analyst creates, and what rows a scheduled snapshot freezes.
 
 ### The pages Janela serves
 
@@ -444,9 +461,11 @@ bin/rails janela:doctor
 Reads your application and lists what still needs doing: identifiers left over
 from an earlier version, Stimulus controllers you have not registered, tables
 you have not migrated, a `through:` dimension whose associated model does not
-allowlist the attribute, a policy that scopes frames by an owner you never
-supply, and whether the engine is mounted and authenticated. It exits non-zero
-when it finds an error, so it works in CI. It only reads and reports.
+allowlist the attribute, a controller that defines no `policy_scope` at all, a
+policy that scopes frames by an owner you never supply, snapshots stored with
+no owner under a policy that filters on one, and whether the engine is mounted
+and authenticated. It exits non-zero when it finds an error, so it works in
+CI. It only reads and reports.
 
 Every finding names the check that produced it:
 
@@ -478,13 +497,13 @@ Janela ships the load-bearing core of a BI tool and nothing else. The reasoning
 - **Querying rides on [Ransack](https://github.com/activerecord-hackery/ransack)'s association-path traversal.** Janela does not invent a query language.
 - **Cross-filtering is a Stimulus controller plus Turbo Frames.** Click a value in one pane, shared filter state updates, every other frame on the page re-renders.
 - **Charts are [Chart.js](https://www.chartjs.org)**, driven by one small Stimulus controller from the same values the tables show. Not a charting engine.
-- **Publishing creates a Snapshot.** An ActiveJob freezes the result set into a new record; the live dashboard stays editable and the published view is a point-in-time fork, not a toggle on the same record. Not built yet.
+- **Publishing creates a Snapshot.** An ActiveJob freezes the result set into a new record; the live dashboard stays editable and the published view is a point-in-time fork, not a toggle on the same record. The job will not freeze a scope you have not named (ADR 034).
 
 Deliberately out of scope: natural-language query, a separate data warehouse, a row-level-security subsystem (use your app's Pundit/CanCanCan), refresh-scheduling UI (schedule the Snapshot job with whatever you already use), embedding SDK, mobile app, print/paginated reports. If you need one of those, the codebase is meant to be small enough to fork and add your own.
 
 ## Status
 
-**v0.6.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames, STI subclasses, the engine's own pages for reading and editing them and the optional vitral theme work and are covered by unit and real-browser tests. Not yet built: a visual editor, drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.8.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering with multi-selection, bar and line charts, pane URLs, shareable dashboard URLs, snapshots, database-backed frames, STI subclasses, the engine's own pages for reading and editing them and the optional vitral theme work and are covered by unit and real-browser tests, with the classes a theme may target documented in [Theming Janela](docs/theming.md). Not yet built: a visual editor, drill-down on time panes, other chart types. [Where Janela Is Going](docs/roadmap.md) says what 1.0 means and which of these are in it; open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

data/UPGRADING.md

@@ -12,6 +12,173 @@ bin/rails janela:doctor
 
 It reads your application and lists what still needs changing.
 
+## 0.7.0 to 0.8.0
+
+Two steps, each only if it applies to you: one if you name a parent
+controller, one if you wrote CSS against Janela's own pages. The doctor
+also starts reporting things it always should have; that needs nothing
+from you but a read.
+
+**1. Set `Janela.parent_controller` in an initializer, if you set it.**
+
+`Janela::ApplicationController` resolves its superclass once, the first
+time the class loads. Naming a different one after that did nothing at
+all, in silence, so your dashboards kept inheriting whatever was named
+first and your authentication and `policy_scope` were not the ones you
+wrote. It raises now rather than being ignored.
+
+```ruby
+# config/initializers/janela.rb   <- runs before anything can load it
+Janela.parent_controller = "Admin::BaseController"
+```
+
+Too late, all of them: `config.to_prepare`, `config.after_initialize`,
+an `initializer` block ordered after `load_config_initializers`, and
+anything that runs once the application is serving. The README's own
+recipe for giving Janela a layout is a `to_prepare` block that loads the
+controller, so if you use that, the initializer has to come first, and
+it does.
+
+Naming the controller Janela already inherits is still allowed, because
+nothing is being asked for.
+
+**2. Check any CSS you wrote against Janela's own pages.**
+
+ADR 016 said "the class names are public API", which read literally
+promised that `janela-card`, `janela-crumb`, `janela-flash`,
+`janela-button`, `janela-form` and the rest of the chrome the engine
+renders on *its own* pages would never be renamed without an entry here.
+That was a promise made to nobody about markup only the engine draws,
+and it made Janela's own pages harder to change than the library they
+serve.
+
+They are now scoped under `janela-page`, which only the engine's own
+layout sets, so they cannot reach your pages, and they may change in any
+release. Nothing is renamed in this release, so nothing breaks today. If
+you styled Janela's own pages by targeting those class names, that
+stylesheet is no longer standing on a contract.
+
+What *is* the contract is unchanged: everything your own markup
+contains, the grid scale and the pane primitives.
+[docs/theming.md](docs/theming.md) lists all of it, the three custom
+properties that carry `janela.css`, and what a theme is expected to
+leave alone.
+
+**What to expect from the doctor.** Two checks that could not fire for
+an application whose `policy_scope` reaches for the signed in user now
+do, so `bin/rails janela:doctor` may report findings that were always
+true and never printed. `unscoped-reads` calls your `policy_scope`
+rather than looking for the method, which catches a Pundit application
+with no policy for `Janela::Frame` or `Janela::Snapshot`: that used to
+pass the doctor and raise on every request.
+`hardcoded-disallowed-predicates` drops to a warning and says a file
+*mentions* a key rather than claiming it filters a model, because it
+only ever grepped for the name.
+
+## 0.6.0 to 0.7.0
+
+Janela has stopped guessing what may be read, in the two places it used
+to default to every row: a pane in a request (ADR 032) and a scheduled
+snapshot (ADR 034). Three steps, and most applications have already
+taken the first.
+
+**1. Say what may be read, if you have not.**
+
+If your `ApplicationController` defines `policy_scope`, nothing changes.
+If you use Pundit, nothing changes. If neither is true, every dashboard,
+pane and inline frame now raises `Janela::Unscoped` where it previously
+totalled every row:
+
+```ruby
+ class ApplicationController < ActionController::Base
++  private
++    def policy_scope(model) = model.all
+ end
+```
+
+That line is an assertion, not a formality: it says every visitor who can
+reach a dashboard may read every row of every model on it. "One tenant"
+and "nothing here is worth hiding from staff" are different claims, and
+only the second one licenses `model.all`. If it is not true of your
+application, return something narrower.
+`docs/multi-tenancy.md` has the wiring for acts_as_tenant, CanCanCan and
+the rest.
+
+Find it before a visitor does:
+
+```bash
+bin/rails janela:doctor
+```
+
+`unscoped-reads` reports the absence as an error and prints the line to
+add.
+
+**2. Take the snapshot owner migration, if you use snapshots.**
+
+`janela_snapshots` gains a nullable polymorphic owner so your policy can
+filter a snapshot the way it already filters a frame:
+
+```bash
+bin/rails janela:install:migrations
+bin/rails db:migrate
+```
+
+Existing snapshots keep a nil owner and keep working. Pass `owner:` when
+you take new ones, and add `Janela::Snapshot` to whatever your policy
+already does for `Janela::Frame`:
+
+```ruby
+- Janela::Snapshot.take(name: "September") { |take| ... }
++ Janela::Snapshot.take(name: "September", owner: Current.account) { |take| ... }
+```
+
+The owner says who a snapshot belongs to. What the numbers inside it
+cover is the next step.
+
+**3. Tell `Janela::SnapshotJob` what rows to freeze, if you schedule
+snapshots.**
+
+The job used to take every pane over the model's default scope, which is
+your tenant's rows if your tenancy is enforced on your models and every
+row if it lives in your policies. Janela cannot tell which application it
+is in, so it has stopped choosing (ADR 034). It now raises
+`Janela::Unscoped` unless you answer.
+
+If your tenancy is on your models, or you have one tenant, say so:
+
+```ruby
+- Janela::SnapshotJob.perform_later(name: "September", panes: [...])
++ Janela::SnapshotJob.perform_later(name: "September", 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. Answer in Ruby instead, and
+schedule your own job:
+
+```ruby
+class TenantSnapshotJob < Janela::SnapshotJob
+  private def scope_for(model) = model.where(account: owner)
+end
+```
+
+Override `scope_for` and the `scope:` argument is not consulted, because
+the method that reads it is the one you replaced. `name`, `owner` and
+`filters` are readable beside it, so there is no need to override
+`perform`. This replaces the old advice to write a job around
+`Snapshot.take` from scratch, which still works and is now one method
+longer than it needs to be.
+
+**Drain the queue, or expect the retries.** A `SnapshotJob` enqueued
+before you deploy was serialised without `scope:` and will raise when it
+performs. Nothing in the diff shows you this. Let the queue empty before
+deploying, or re-enqueue what fails afterwards.
+
+**What did not change.** `Order.janela.query(:revenue)` called from your
+own Ruby still runs over `Order.all`, because you wrote that call and the
+scope was yours to choose. Only what Janela decides on your behalf inside
+a request has stopped guessing. Frames, pane rows and snapshots are read
+through the same scope they always were.
+
 ## 0.5.0 to 0.6.0
 
 How single table inheritance is handled changed (ADR 031). Nothing here

data/app/assets/stylesheets/janela.css

@@ -87,6 +87,27 @@ table.janela-pane button[aria-pressed="true"] { background: var(--janela-accent)
 
 canvas.janela-chart { width: 100% !important; max-height: 20rem; }
 
+/* A host whose own markup already says what a pane is puts this on any
+   ancestor, and the caption and the single value's label stop being drawn
+   without leaving the accessibility tree. Hidden rather than removed on
+   purpose: a caption is the table's accessible name, so display: none would
+   land a screen reader on a grid of numbers with nothing to say what they
+   measure. The rule ships here because that is easy to get wrong and every
+   host would otherwise write it (ADR 036, #26). A chart pane needs nothing:
+   its title was only ever an aria-label. */
+.janela-own-headings table.janela-pane caption,
+.janela-own-headings .janela-value-label {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
 /* Janela's own pages (ADR 013). Scoped to a class the engine's layout sets,
    so including this stylesheet changes nothing about a host's own pages. */
 .janela-page {

data/app/controllers/janela/application_controller.rb

@@ -27,9 +27,10 @@ module Janela
 
       # Pundit defines policy_scope on the host's ApplicationController, which
       # this inherits from, so authorisation applies without Janela depending
-      # on Pundit or being configured.
+      # on Pundit or being configured. A host that defines nothing is refused
+      # rather than answered with every row (ADR 032).
       def janela_scope(model)
-        respond_to?(:policy_scope, true) ? policy_scope(model) : model.all
+        Janela.scope(self, model)
       end
 
       # A host that scopes frames by owner would hide a frame created without

data/app/helpers/janela/frames_helper.rb

@@ -51,9 +51,11 @@ module Janela
       end
 
       # A frame rendered inline runs its queries in the host's own request, so
-      # the same Pundit scope the engine's controllers apply is applied here.
+      # the same scope the engine's controllers apply is applied here. The
+      # controller is asked, not the view, and the question itself lives in
+      # one place so the two can never disagree again (#46, ADR 032).
       def janela_scope(model)
-        respond_to?(:policy_scope, true) ? policy_scope(model) : model.all
+        Janela.scope(controller, model)
       end
 
       def janela_page_filters

data/app/jobs/janela/snapshot_job.rb

@@ -1,18 +1,59 @@
 module Janela
   # Takes a snapshot from serialisable arguments so a host can schedule it
-  # with whatever runs its jobs. Each pane uses its model's default scope; a
-  # host that scopes by tenant writes its own job around Snapshot.take and
-  # passes on: (ADR 009).
+  # with whatever runs its jobs.
+  #
+  # What rows each pane freezes is the host's answer rather than Janela's. A
+  # host whose tenancy is enforced on its models says so with
+  # scope: :model_default; a host whose tenancy lives in its policies
+  # subclasses this and overrides scope_for, because a class name crosses the
+  # queue where a relation cannot (ADR 034).
   class SnapshotJob < ActiveJob::Base
-    def perform(name:, panes:, filters: {})
-      Snapshot.take(name: name, filters: filters) do |take|
+    # ActiveJob cannot serialise a relation, which is why on: is not an
+    # argument here, but it serialises a record through its GlobalID, so an
+    # owner crosses the queue boundary without anything new (ADR 033).
+    def perform(name:, panes:, owner: nil, filters: {}, scope: nil)
+      @name, @owner, @filters, @scope = name, owner, filters, scope&.to_sym
+
+      Snapshot.take(name: name, owner: owner, filters: filters) do |take|
         panes.each do |pane|
           pane = pane.to_h.stringify_keys
           model = Janela.definition!(pane.fetch("model")).model
-          take.pane(model, pane.fetch("measure").to_sym,
+          take.pane(model, pane.fetch("measure").to_sym, on: scope_for(model),
                     by: pane["by"]&.to_sym, granularity: pane["granularity"], limit: pane["limit"])
         end
       end
     end
+
+    private
+      # What the job was told, so a subclass answering scope_for never has to
+      # override perform or reach into ActiveJob's arguments to find it.
+      attr_reader :name, :owner, :filters
+
+      # The one question this job asks, and the one it will not answer on a
+      # host's behalf: what rows does a pane freeze? A model's default scope
+      # is the tenant's rows when tenancy is enforced on the models, and every
+      # row when it lives in a policy, and nothing reachable from a job can
+      # tell which application this is. Unanswered it refuses, because the
+      # wrong answer here is frozen into a row and published (ADR 034).
+      def scope_for(model)
+        raise Unscoped, unanswered if @scope.nil?
+        raise ArgumentError, "#{@scope.inspect} is not a scope Janela knows. Pass :model_default, " \
+                             "or override scope_for in a subclass of Janela::SnapshotJob." unless @scope == :model_default
+
+        model.all
+      end
+
+      def unanswered
+        "Janela::SnapshotJob has not been told what rows to freeze. If your tenancy is enforced " \
+        "on your models, a model's default scope is already the rows you mean, and saying so is " \
+        "the whole of it:\n\n" \
+        "  Janela::SnapshotJob.perform_later(name: \"September\", scope: :model_default, panes: [...])\n\n" \
+        "If your scoping lives in your policies instead, that is every row of every model. " \
+        "Answer in Ruby, where a relation is still a relation, and schedule your own job:\n\n" \
+        "  class TenantSnapshotJob < Janela::SnapshotJob\n" \
+        "    private def scope_for(model) = model.where(account: owner)\n" \
+        "  end\n\n" \
+        "docs/multi-tenancy.md has the wiring."
+      end
   end
 end

data/app/models/janela/snapshot.rb

@@ -4,15 +4,24 @@ module Janela
   # live dashboard stays editable (ADR 009). Results are stored, not HTML; the
   # renderer is chosen by whoever shows a stored pane.
   class Snapshot < ActiveRecord::Base
+    # Janela sets what it is handed and reads nothing from it. The column
+    # exists so a multi tenant host's policy has something to filter a
+    # snapshot on, the same as a frame's (ADR 033).
+    belongs_to :owner, polymorphic: true, optional: true
+
     attribute :filters, default: -> { {} }
     attribute :panes, default: -> { [] }
 
     validates :name, :taken_at, presence: true
 
-    def self.take(name:, filters: {}, taken_at: Time.current)
+    # The owner is an argument rather than something asked of a controller,
+    # because a snapshot is never taken in a request: this runs in a job, a
+    # task, a console or a host's own code, and the caller is the only thing
+    # that knows the answer (ADR 033).
+    def self.take(name:, owner: nil, filters: {}, taken_at: Time.current)
       taking = Taking.new(filters.to_h.stringify_keys)
       yield taking
-      create!(name: name, taken_at: taken_at, filters: taking.filters, panes: taking.panes)
+      create!(name: name, owner: owner, taken_at: taken_at, filters: taking.filters, panes: taking.panes)
     end
 
     def stored_result(query)

data/db/migrate/20260921000001_add_owner_to_janela_snapshots.rb

@@ -0,0 +1,9 @@
+class AddOwnerToJanelaSnapshots < ActiveRecord::Migration[8.0]
+  def change
+    # Janela never reads the owner. It is here so a host's Pundit Scope has
+    # something to filter a snapshot on, the same as a frame's (ADR 033).
+    # Nullable, because a snapshot nobody owns is invisible to a policy that
+    # filters on one, which is the safe direction to fail.
+    add_reference :janela_snapshots, :owner, polymorphic: true, null: true
+  end
+end

data/docs/decisions/009-snapshots.md

@@ -2,7 +2,7 @@
 Date: 2026-09-15
 Status: Accepted
 Related: ADR 001, ADR 002, ADR 005, ADR 008, ADR 012
-Superseded in part by: ADR 012
+Superseded in part by: ADR 012, ADR 033, ADR 034
 Triggers:
   - publishing a dashboard or pane for an audience that must not see live data or slicers
   - adding a database table, migration or model to the engine