janela 0.5.0 → 0.7.0

data/docs/decisions/029-a-panes-frame-is-identified-by-who-it-is.md

@@ -0,0 +1,112 @@
+---
+Date: 2026-09-18
+Status: Accepted
+Related: ADR 003, ADR 005, ADR 012, ADR 014, ADR 024
+Superseded in part by: ADR 030
+Triggers:
+  - changing how a pane's turbo frame is identified
+  - adding a parameter to a pane URL
+  - a host wanting a control over a pane's own settings
+  - a frame that does not update when it should
+Topics: cross-filtering, panes, urls, host-integration
+---
+
+# ADR 029: A Pane's Frame Is Identified by Who It Is, Not by What It Shows
+
+## Context
+
+Issue #42 found that pointing a pane's turbo frame at a URL differing only
+in `limit`, `granularity` or `as` makes Turbo fetch the response and then
+silently do nothing: no render, no `frame-missing`, no console error, the
+frame left showing the old numbers forever. Measured in a browser, not
+inferred.
+
+The cause is that `Query.turbo_frame_id` builds the id out of the query
+itself, renderer, granularity and limit included, so the response comes
+back wearing a different id from the frame that asked for it. Turbo has
+nothing to reconcile and gives up quietly.
+
+**The project has already solved this once, in the half that does not have
+the bug.** A pane that is a record uses `Pane#turbo_frame_id`, which is
+`janela_pane_#{id}`, and the comment on it says exactly why:
+
+> The DOM id is the row, not the query it runs: two rows in one frame may
+> show the same measure by the same dimension, and a fingerprint of the
+> query would give them the same turbo frame for Turbo to replace.
+
+That is ADR 014's reasoning, and it is right. A record-backed pane can
+change its renderer, its granularity and its limit all day and its frame
+id never moves, because the id says who the pane is rather than what it
+is currently showing.
+
+The helper path has no row to point at, so it fingerprints the query
+instead. The fingerprint is not arbitrary: without it, two `janela_pane`
+calls for the same measure by the same dimension would collide, and one
+would replace the other. So the fingerprint solves a real problem and
+creates this one.
+
+The reason this has not bitten the library itself is worth stating: a
+click changes filters, and filters are deliberately not in the id, so
+every navigation Janela performs keeps the id stable. It is only a host
+reaching for the URL's other documented parameters that falls in, and
+what it gets is stale numbers with no error, which is the worst failure
+this library has (ADR 003).
+
+## Decision
+
+**`janela_pane` accepts an `id:`, and a pane given one is identified by
+it rather than by a fingerprint of its query.**
+
+1. The fingerprint stays the default. It is correct for the common case,
+   a page of unlike panes with no controls over them, and it is what
+   keeps two alike panes apart.
+2. A host that wants to change a pane's settings in place names that
+   frame itself. The id is then stable by construction, because it comes
+   from the host rather than from the query, and Turbo reconciles
+   normally. This is the same move ADR 012 made for a record-backed pane,
+   made available to a pane that is not a record.
+3. The response wears the id the frame asked for rather than one derived
+   again from the query. This needs no new surface at all: Turbo already
+   sends the requesting frame's id in the `Turbo-Frame` header, and
+   turbo-rails exposes it as `turbo_frame_request_id`. So a pane rendered
+   into a frame request answers to the frame that asked, and a pane
+   rendered any other way keeps deriving its own id as it does now. The
+   pane URL does not grow a parameter, which was the first thing this
+   decision reached for and did not need.
+4. The failure is documented rather than left to be discovered. A host
+   that changes a pane's URL without naming its frame gets the silent
+   staleness described above, and the README says so where it describes
+   the pane URL's parameters.
+
+## What this turns down
+
+**Taking renderer, granularity and limit out of the fingerprint.** It
+would fix #42 and reintroduce the collision ADR 014 avoided: the gallery
+renders the same measure by the same dimension as a bar and as a line on
+one page, and those two must not share a frame. The fingerprint is doing
+real work.
+
+**Leaving it to every host to fetch and swap the frame themselves**, which
+is what the demo's gallery does today and what proved the diagnosis. It
+works, and it asks each host to write the same Stimulus controller and to
+know a thing about Turbo's id matching that nothing told them. ADR 001
+says ship the load-bearing 5%: a frame that updates when its URL changes
+is inside that, and a host reimplementing frame reconciliation is not.
+(Superseded in part by ADR 030: a frame does not update when its URL
+changes, because `src` is not a channel a host can speak through. What is
+inside the 5% is a pane that goes where it is asked to, which is the same
+thing said correctly.)
+
+## Consequences
+
+`janela_pane` grows one optional keyword argument, and a host that never
+passes it sees no change at all. The demo's gallery control becomes
+smaller, since the frame can be navigated rather than swapped by hand,
+and that is the check on whether this decision is right: if the control
+does not get simpler, the decision was wrong.
+
+Two alike panes given the same `id` by a host would collide, which the
+fingerprint prevented automatically. That is the cost of letting a host
+name things, it is the same cost a host already carries for every DOM id
+it writes, and the doctor is the place to notice it if it turns out to
+happen.

data/docs/decisions/030-a-panes-src-belongs-to-turbo.md

@@ -0,0 +1,93 @@
+---
+Date: 2026-09-18
+Status: Accepted
+Related: ADR 003, ADR 005, ADR 024, ADR 029
+Supersedes: part of ADR 029
+Triggers:
+  - a host changing what a pane shows from JavaScript
+  - writing to a turbo frame's src from anything but Turbo
+  - adding a data attribute the frame controller reads
+  - anything that would reintroduce reading intent out of the DOM
+Topics: cross-filtering, panes, host-integration, javascript
+---
+
+# ADR 030: A Pane's src Belongs to Turbo, So a Host Talks to the Frame
+
+## Context
+
+ADR 029 gave a host a way to name a pane's frame so it could be
+reconfigured in place, and said that "a frame that updates when its URL
+changes is inside" the load-bearing core. Building it showed that is not
+true, and the reason is a decision this project already made.
+
+#33 established that a frame's `src` does not describe what that frame
+is showing. Turbo writes `src` back onto a frame when a response lands,
+including a late one for a request that has since been superseded. So
+`janela--frame` keeps its own record of what was asked for and reverts
+anything that does not match it:
+
+> The request for what Janela last asked for wins, and any other is
+> reverted. What was asked for is the only honest rule (#33).
+
+That rule is right, and its consequence was not drawn at the time: if
+the controller's own record is the only trustworthy statement of intent,
+then `src` is no longer a channel a host can speak through. A host that
+follows ADR 029, names a pane and writes `frame.src`, has its request
+aborted and the frame put back, with no error and the old numbers still
+on screen. That is the failure #42 was about, reached by following the
+instructions written to fix #42.
+
+There is no way to tell a host's `src` write from Turbo's. Any attempt,
+a mutation observer, a flag, a heuristic on the attribute, re-infers
+intent from the DOM, which is exactly what #33 removed because it
+produced wrong numbers.
+
+And the record is not one attribute. A pane also carries the base URL
+the controller rebuilds from on the next click, so a host writing the
+record by hand has to write two attributes in the right order, and
+reapply the frame's current filters itself. Only the frame controller
+knows those filters. The demo's own gallery control got that wrong:
+reconfigure a pane while a filter is active and it refetches unfiltered
+while every pane beside it stays filtered (#43).
+
+## Decision
+
+**A host changes what a pane shows by asking `janela--frame`, and never
+by writing `src` or a data attribute.**
+
+The controller already does this for itself when the frame's filters
+change. Making that reachable is extraction rather than new surface: one
+way to ask a pane to go to a different query, which records what was
+asked, reapplies the frame's filters and sets `src` in the order the
+guard expects.
+
+Three things follow.
+
+1. **The data attributes are private.** `janelaAsked` and `janelaSrc` are
+   how the controller remembers, not an interface. A host that writes
+   them is relying on something that may change.
+2. **A reconfigured pane stays cross-filtered.** Reapplying the frame's
+   current filters is part of repointing, not something a caller
+   remembers, because forgetting it shows numbers for the wrong filter
+   state and says nothing (ADR 003).
+3. **`id:` is still necessary.** ADR 029 stands: without a stable frame
+   id there is nothing to repoint. It is necessary and it was not
+   sufficient, which is what this records.
+
+## Consequences
+
+ADR 029's claim that a frame updates when its URL changes is untrue as
+written, and this supersedes that sentence rather than the decision. The
+`id:` keyword and answering a frame request with the id Turbo sent are
+both correct and stay.
+
+A host reconfiguring a pane writes one call instead of three writes it
+was never told about, and gets the filter behaviour right by default
+rather than by knowing to. The demo's gallery control is the check, the
+same way it was for ADR 029: it should get smaller again, and its filter
+bug should disappear rather than be fixed separately.
+
+The cost is one public method on a Stimulus controller, which is a
+surface this project did not have before. It earns itself by removing a
+class of silent wrongness rather than by adding capability, which is the
+kind of addition ADR 001 leaves room for.

data/docs/decisions/031-a-subclass-inherits-the-dashboard.md

@@ -0,0 +1,110 @@
+---
+Date: 2026-09-19
+Status: Accepted
+Related: ADR 002, ADR 013, ADR 014, ADR 025, ADR 028
+Triggers:
+  - subclassing a model that declares a janela block
+  - changing what is addressable over HTTP
+  - changing how the registry is populated
+  - adding to the Ransack allowlist a model gets from Janela
+Topics: configuration, urls, security, scope
+---
+
+# ADR 031: A Subclass Inherits the Dashboard Its Parent Declared
+
+## Context
+
+`janela` stores its definition in a plain class instance variable, so a
+subclass of a model that declares one gets `nil` from `.janela` and is
+not in the registry (#11).
+
+Reproducing it found something the issue did not say. The subclass does
+inherit the Ransack allowlist, because
+`define_janela_ransack_allowlist` defines singleton methods on the
+parent and singleton methods inherit down the singleton class chain:
+
+```
+subclass .janela:      nil
+subclass ransackable:  ["status", "channel", "placed_on"]
+```
+
+So a subclass is already half declared: filterable on the parent's
+dimensions, with no definition behind it saying what those dimensions
+are. Neither half was decided. One was written and the other happened.
+
+The instinct is to walk the ancestors in `janela`, which fixes `.janela`
+and does not fix the bug. What a host wants from an STI subclass is a
+dashboard of it, and that needs the subclass registered:
+
+```ruby
+janela_pane PaidOrder, :revenue   # src is /paid_orders/revenue
+```
+
+An inherited definition with no registration renders that pane and then
+404s it. That is worse than today, because today the failure is loud at
+the call site and that one is a dead pane on a page.
+
+So the question is not whether the definition inherits. It is whether
+being a subclass makes a model addressable, and `lib/janela.rb` states
+the current answer plainly:
+
+> Only models that declare a janela block are addressable over HTTP
+
+## Decision
+
+**A subclass inherits its parent's definition and is addressable on its
+own route key. Declaring is what a family of classes does once.**
+
+The argument that settles it is about data rather than URLs. An STI
+subclass is a subset of its parent's rows. If the parent is addressable,
+the subclass reveals no row the parent does not already total, and it is
+read through the same host scope as everything else (ADR 014). So this
+adds URL surface and no data surface, which is a much smaller thing than
+the rule above makes it sound.
+
+Three things follow.
+
+1. **The halves agree.** The definition inherits, the registration
+   inherits, and the Ransack allowlist keeps inheriting as it already
+   does. A subclass is either a Janela model or it is not, rather than
+   being one in the part nobody chose.
+2. **STI scoping is ActiveRecord's, not Janela's.** A definition whose
+   model is the subclass runs its query on that class and ActiveRecord
+   adds the `type` condition itself. Janela learns nothing about STI,
+   which is the right amount for it to know.
+3. **A subclass may still declare its own block**, and then it has its
+   own definition rather than its parent's, which is how a subclass says
+   its dashboard is different.
+
+Registration cannot happen where declaration happens, because the
+subclass does not exist when the parent declares. It happens when the
+subclass is created.
+
+## What this turns down
+
+**Inheriting nothing, and documenting that each subclass declares its
+own.** It is the most conservative reading and it asks a host with five
+STI types to retype the same measures and dimensions five times. ADR 002
+spent Ransack's familiarity on the host deliberately; spending their
+typing on a class hierarchy Rails already models is a worse trade.
+
+**Inheriting the definition without registering.** Rejected above: a
+helper that renders a pane which cannot load.
+
+## Consequences
+
+The honest cost is not security, it is noise. `Janela.definitions` feeds
+the form that offers a choice of model when an analyst adds a pane
+(ADR 012), and a host with a dozen STI types will see a dozen entries
+where it expected one. That is a real cost and it is the thing to watch:
+if it becomes the complaint, the answer is a way for a family to say
+which of its classes are worth offering, and that is a later decision
+rather than a setting invented now.
+
+The check on whether this decision is right is what a host writes. If
+adding a dashboard for an STI subclass still takes anything beyond
+creating the class, the decision did not deliver.
+
+The demo has no STI model, so proving this takes one: a `type` column on
+a table and a subclass in the dummy. That is a fixture, and adding it is
+part of the work rather than a reason to avoid it.

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.

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.