janela 0.6.0 → 0.8.0

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

@@ -0,0 +1,157 @@
+---
+Date: 2026-09-20
+Status: Accepted
+Related: ADR 002, ADR 004, ADR 015, ADR 019, ADR 021, ADR 025
+Superseded in part by: ADR 035
+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.

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.