janela 0.6.0 → 0.7.0

data/docs/decisions/033-a-snapshot-is-told-who-owns-it.md

@@ -0,0 +1,151 @@
+---
+Date: 2026-09-21
+Status: Accepted
+Related: ADR 002, ADR 009, ADR 014, ADR 019, ADR 032
+Triggers:
+  - adding an owner or a tenancy column to anything the engine stores
+  - creating a record outside a request, in a job, a task or a console
+  - scheduling a snapshot, or writing a job around Snapshot.take
+  - a snapshot the wrong audience can read
+  - extending ADR 019's controller hook to something new
+Topics: snapshots, tenancy, authorisation, persistence, activejob, host-integration
+---
+
+# ADR 033: A Snapshot Is Told Who Owns It, Because There Is No Request to Ask
+
+## Context
+
+`janela_snapshots` holds a name, an instant, the filters it was taken
+under and the results. It has no owner column, so
+`policy_scope(Janela::Snapshot)` has nothing to filter on. ADR 014 gave
+a frame a nullable polymorphic owner for exactly this reason and said
+Janela never interprets it. A snapshot never got the same.
+
+The guide calls this the rough edge and offers three workarounds: keep
+snapshots to one tenant, add a column of your own, or encode the tenant
+in the filters and scope on the name. The demo does the first, crudely
+and on purpose. None of them are a column a policy can filter on.
+
+Measured against the demo's fixtures before deciding anything:
+
+```
+every order:                       375.0
+one tenant's orders:               150.0
+what Janela::SnapshotJob stored:   375.0
+what take with an explicit on:     150.0
+owner column on janela_snapshots:  none
+```
+
+Two separate problems sit in those five lines, and only the first is
+this ADR's.
+
+**A snapshot cannot be owned.** There is nowhere to put the answer, so a
+multi tenant host cannot scope reads of one.
+
+**Janela's own job chooses a scope.** `SnapshotJob` calls `take` with no
+`on:`, which ADR 009 decided deliberately, because a job cannot receive
+a relation. Whether that is wrong depends on where a host keeps its
+tenancy: at the model layer, through acts_as_tenant or a default scope,
+`model.all` is already the tenant's rows and the job is correct, which
+is what the guide's own example means by "acts_as_tenant has already
+scoped your own models". At the policy layer, through Pundit or
+CanCanCan, it is every row and the host's scope never runs. Janela
+cannot tell which it is in, so what it has is a default chosen by the
+library where ADR 032 would have it stated by the host. Not solved
+here: it is a different question with a different shape, and folding it
+in would make this one about two things. Filed as #47 so it cannot be
+lost.
+
+The interesting part of the first problem is where the answer comes
+from. ADR 019 settled that for a frame by asking the host's controller
+for `janela_frame_owner`, and generalised it into a precedent. It does
+not reach here. A frame is created in a request, by an analyst using
+the engine's own form, so there is a controller to ask and a
+`Current.tenant` to ask it about. A snapshot is never created in a
+request: there is no create route, no controller action and no form,
+only `Snapshot.take` called from a job, a rake task, a console or a
+host's own code. Verified rather than assumed, by reading every call
+site in the repository.
+
+So the options were not "which hook" but "what does a method called
+outside a request know".
+
+**A controller hook anyway**, with `Snapshot.take` reaching for
+`Current.something`. Rejected: it would work in a console and quietly
+return nil in the job that is the whole point of the feature, which is
+the silent-failure shape ADR 019 was written to avoid in the first
+place.
+
+**A setting**, `Janela.snapshot_owner = -> { ... }`. Rejected on ADR
+019's own reasoning, which found that a judgement needing the current
+tenant cannot live in a setting, and on ADR 001, since it is a second
+way to answer a question an argument already answers.
+
+**Inferring it from the panes' relations.** Rejected as impossible
+rather than unwise: a relation does not name a tenant, and reading one
+to guess would be Janela interpreting an owner, which ADR 014 forbids.
+
+## Decision
+
+**A snapshot's owner is an argument to `Snapshot.take`, because the
+caller is the only thing that knows it.**
+
+```ruby
+Janela::Snapshot.take(name: "September 2026", owner: Current.account) do |take|
+  take.pane Order, :revenue, on: policy_scope(Order)
+end
+```
+
+`janela_snapshots` gains nullable polymorphic `owner_type` and
+`owner_id`, the same shape as a frame's, through the usual
+`rails janela:install:migrations`. Janela assigns what it is handed and
+reads nothing from it. Scoping stays entirely the host's policy, exactly
+as ADR 014 said of a frame.
+
+**`SnapshotJob` takes an `owner:` too.** ActiveJob serialises an
+ActiveRecord object through its GlobalID, so unlike a relation an owner
+crosses the queue boundary without anything new being invented.
+
+**The owner is optional.** ADR 032 narrowed ADR 019's
+silence-as-an-answer rule to permit it only where the silent default is
+the narrow one, and named a nil owner as the example. A snapshot nobody
+owns is invisible to a policy that filters on owner, which is the safe
+direction to fail, and correct for a single tenant application where
+nothing is filtering on it.
+
+**This ADR does not extend ADR 019, it bounds it.** The rule is now
+legible: the engine asks the host's controller when the engine is the
+thing doing the creating inside a request, and takes an argument when
+the host is. A future record written by Janela should be read against
+which of those two it is, rather than reaching for the controller hook
+because a frame does.
+
+## Consequences
+
+- A multi tenant host can scope snapshots with the same policy it
+  already writes for frames, and the guide loses its rough edge.
+- A migration a host must run, so it goes in `UPGRADING.md` with the
+  install task and the fact that existing snapshots keep a nil owner
+  (ADR 015). Nothing breaks for a host that ignores it.
+- `Snapshot.take`'s signature grows one keyword with a default, so every
+  existing call keeps working unchanged.
+- **The shipped `SnapshotJob` still picks each model's default scope.**
+  Right for a host whose tenancy is in the model layer, silently wrong
+  for one whose tenancy is in its policies. Adding an owner sharpens
+  that rather than softening it: the snapshot is now scopable, so its
+  contents are the only unscoped thing left, and a host may reasonably
+  read the new column as a promise the numbers inside do not keep. This
+  wants its own decision and has one, #47; until it is settled the guide
+  has to keep saying plainly that a policy scoped host writes its own
+  job.
+- Janela reads nothing from the owner, so a host that assigns one and
+  writes no policy has changed nothing. That is the frame's trap again,
+  and `frames_nobody_will_own` is the doctor check that catches the
+  frame version. The snapshot version is not the same shape, because the
+  caller assigns the owner in its own Ruby rather than the engine doing
+  it silently, so it is a thinner case for a check. Worth revisiting if
+  it bites.
+- What would change this decision: a snapshot being created inside a
+  request, through an engine form the way a frame is. That would put a
+  controller back in the picture and make ADR 019's hook the consistent
+  answer, and this ADR should be read again rather than worked around.

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, 029, 030 |
+| **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, 031 |
+| **Security** | 003, 025, 028, 031, 032, 034 |
 | **Testing** | 003 |
 
 ## Chronological
@@ -76,7 +76,10 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 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: 032
+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/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/version.rb

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