janela 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fd31f19d1b100c312826e8077aefc291873c0cc153410aa9c53199dcdf5ba18
-  data.tar.gz: ec551cd6c640de00e6ba13266ae2920945f68ad4a576c344e157830c9442563d
+  metadata.gz: 91a8da061f836f0c93ed3c6005f704fc8c5830ea2fb8e73f2f77c96f2107c467
+  data.tar.gz: ace46d3c7c08ea5423de350f14dcd17e6a303528f62f2a3c60b66b9bf2cc88bf
 SHA512:
-  metadata.gz: 692add30c86d3633d3144b6fe1fbb138246762e974f618430db2f290f1980a91bb55441104b2a1d183e67e6e16ca3ffd75aaab8d8e0156d77444950bc388dc21
-  data.tar.gz: 794ac1f1352ee3e30357d8ef2ff7bd2d0692895f932b3aec5d3acc5df55ab21e592397f111df855a120c547eea271273807e870d988a602a49c6575987ddaa9a
+  metadata.gz: ce044bb0f401c9541a69952212b22492c94d3d68a7a7ce05af8e568b0a77c16adf41b8153291cbc981c80ad2343a16122989890c00ce6feeb5ee3200605ebc82
+  data.tar.gz: 1244329924141334f04b3d4f4ac0f15834862d110d0577f5a3739ff2085549a790d76691941df362080a1b470de6927773a3a4cd0cda963f62cb3ca31e0640a4

data/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.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 +169,7 @@ 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.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.7"
 ```
 
 ```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,7 +428,7 @@ 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. `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.
 
@@ -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:
 
@@ -484,7 +503,7 @@ Deliberately out of scope: natural-language query, a separate data warehouse, a
 
 ## 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.7.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).
 
 ## Development
 

data/UPGRADING.md

@@ -12,6 +12,110 @@ bin/rails janela:doctor
 
 It reads your application and lists what still needs changing.
 
+## 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/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

data/docs/decisions/032-janela-will-not-read-a-model-it-cannot-scope.md

@@ -0,0 +1,156 @@
+---
+Date: 2026-09-20
+Status: Accepted
+Related: ADR 002, ADR 004, ADR 015, ADR 019, ADR 021, ADR 025
+Triggers:
+  - deciding what Janela should do when a host has configured nothing
+  - adding a hook a host answers by defining a method
+  - a dashboard showing rows the person reading it should not see
+  - choosing a default for anything that decides what may be read
+  - writing a doctor check about authorisation
+Topics: authorisation, tenancy, host-integration, security, configuration, releases
+---
+
+# ADR 032: Janela Will Not Read a Model It Has Not Been Told How to Scope
+
+## Context
+
+`janela_scope` asks the host's controller for `policy_scope` and returns
+`model.all` when there is none. ADR 002 called that authorisation being a
+hook rather than a dependency, and ADR 004 recorded the gap in its
+consequences as "tracked as a pre-public issue". The gem is public now,
+so the condition that deferral was written under has passed.
+
+What the fallback does, measured against the demo with `policy_scope`
+removed from the host, which is the state an application using a
+different authorisation library is already in:
+
+```
+a pane the scope hides, with policy_scope:    404
+the same pane, without:                       200, showing $375.00
+log lines mentioning scope, policy or janela: 0
+```
+
+The request that should be a refusal becomes a number belonging to
+somebody else, with nothing on the page or in the log to say so. Janela
+treats a confidently wrong number as its worst failure, and this is the
+purest form of it: not a pane that errors, a pane that lies.
+
+Two facts narrow who this actually hits, and both were wrong in the
+issue as filed.
+
+**A host using Pundit is not affected, even one missing a policy.**
+Pundit's `policy_scope` resolves through `policy_scope!`, which raises
+`NotDefinedError`. Verified in Pundit 2.5.2: `Authorization#policy_scope`
+calls `pundit_policy_scope`, which calls `pundit.policy_scope!`. A
+forgetful Pundit host gets an exception, which is the correct outcome
+and needs nothing from us. The exposure is a host that defines no
+`policy_scope` at all.
+
+**The two copies of the fallback do not agree with each other.** The
+controller copy asks `self`, which is the controller; the helper copy
+asks the view, which cannot see a private controller method. A host
+following this project's own multi-tenancy guide, which writes
+`policy_scope` as a private method with no `helper_method`, is scoped on
+the engine's pages and unscoped on a frame embedded in its own. That is
+a bug rather than a decision and is tracked separately; this ADR assumes
+it is fixed and that both paths ask the controller.
+
+Four options were considered.
+
+**Log loudly.** Breaks nothing, and a log line in an application that is
+already noisy is close to the silence it replaces. It also leaves the
+wrong number on the screen, which is the part that matters.
+
+**A configured scope resolver**, `Janela.scope = ->(model, controller)`.
+Rejected on ADR 019, which found that a decision needing the current
+user and tenant belongs inside a request rather than in a setting, and
+on ADR 001, because the host's controller already answers this question
+and a second way to answer it is a second thing to understand.
+
+**A doctor check alone.** Rejected as insufficient rather than wrong.
+The guide currently instructs a single tenant host to define nothing, so
+a check flagging that would contradict the documentation a reader just
+followed, which is the false alarm ADR 021 exists to prevent. It is also
+advisory: it speaks at setup time and cannot stop a request.
+
+**Raise.** Chosen, below.
+
+The tension is real. `model.all` is the correct relation for a single
+tenant application, and most applications are single tenant, so raising
+asks something of hosts that were never wrong. Two things settle it.
+This project has met the same shape twice and chosen the same way both
+times: ADR 002 raises where Ransack silently dropped a filter, and ADR
+025 raises where any predicate silently ran. And "single tenant" is not
+the same claim as "every visitor may total every row of every model on a
+dashboard". Today that second claim is made by omission. It should be
+made on purpose or not at all.
+
+## Decision
+
+**Janela raises `Janela::Unscoped` when it would otherwise read a model
+the host has not told it how to scope.** The fallback to `model.all` is
+removed from both the controller and the helper.
+
+A host says what may be read by answering the question Janela already
+asks, in the place it already asks it:
+
+```ruby
+class ApplicationController < ActionController::Base
+  private
+    def policy_scope(model) = model.all
+end
+```
+
+That line is not ceremony. It is the assertion that every visitor who
+can reach a dashboard may read every row behind it, which is a sentence
+a maintainer should have to write rather than inherit.
+
+No new setting. ADR 019's pattern stands: Janela asks the host's
+controller by duck typing and never by configuration.
+
+**It raises at request time, not at boot.** Resolving
+`Janela.parent_controller` during initialisation is a trap this project
+has already paid for, and a boot raise would break a console or a
+migration for a host part way through upgrading.
+
+**It is not rescued into a pane.** A missing scope is not a data
+condition, and dressing it as the sentence a 404 shows would hide the
+thing the host has to fix.
+
+**The doctor gains `unscoped-reads`, at error severity.** Unlike the
+`unauthenticated-endpoints` check, which hedges because authentication
+cannot be determined by reading, this one is exact: the parent
+controller either responds to `policy_scope` or it does not.
+
+## Consequences
+
+- A host that defines no scope stops getting numbers and starts getting
+  an exception naming what to add. Loud, once, instead of quiet forever.
+- Breaking, so it goes in a minor release with an `UPGRADING.md` section
+  and a `post_install_message` (ADR 015). A host using Pundit, or one
+  that followed the multi-tenancy guide, does nothing. A single tenant
+  host writes one method.
+- ADR 004's consequence recording this as a pre-public issue is
+  superseded.
+- **ADR 019 is narrowed rather than superseded.** It generalised taking
+  silence as an answer into a precedent and cited `policy_scope` as the
+  model for it. That precedent survives with a limit: silence is an
+  acceptable answer when the silent default is the narrow one, as a nil
+  owner is, and never when it is the widest one. A future hook that
+  defaults to reading everything is this decision again, not ADR 019.
+- ADR 002's `on:` parameter keeps defaulting to `model.all`. That is a
+  call a maintainer writes in their own Ruby, where the scope is theirs
+  to choose and nothing is being decided on their behalf. The seam is
+  between what Janela chooses inside a request and what a host asks for
+  directly.
+- The multi-tenancy guide's "define nothing" section, its summary table
+  and the README's description of the fallback all become wrong the
+  moment this lands, and change in the same commit.
+- Duck typing still means a typo in the method name reads as absence.
+  Before this, that silently widened the scope; now it raises, so the
+  doctor check is a convenience rather than the only defence.
+- What would change this decision: evidence that the raise fires for
+  hosts that had genuinely done nothing wrong and had no reasonable way
+  to know, in numbers rather than anecdote. A permissive default is not
+  coming back, but where the question is asked could.