janela 0.2.1 → 0.3.0

data/docs/decisions/019-a-created-frame-asks-the-host-who-owns-it.md

@@ -0,0 +1,79 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 002, ADR 004, ADR 012, ADR 014
+Triggers:
+  - creating a frame or any other record on a host's behalf
+  - adding a configuration setting to Janela
+  - a host needing to influence what the engine writes
+  - a record being invisible to the scope that was meant to find it
+Topics: authorisation, tenancy, persistence, host-integration, configuration
+---
+
+# ADR 019: A Created Frame Asks the Host Who Owns It
+
+## Context
+
+ADR 014 gave a frame a nullable polymorphic owner purely so a host's
+Pundit scope has a column to filter on, and said Janela never
+interprets it. That was right while frames were only created in a
+console or a seed, where whoever created one could set it.
+
+Build 4 lets an analyst create a frame through the engine's own form,
+and the gap becomes a fault: Janela writes the row, so Janela decides
+the owner, and it has nothing to decide with. A frame saved with no
+owner is hidden by the very scope meant to find it, so the analyst
+creates a dashboard and it disappears. That failure has already
+happened twice in this project by other routes, once in a test and
+once on the live demo, which is how confidently it can be predicted
+here.
+
+Three ways out. A configuration setting naming the owner. The engine
+not creating frames at all, leaving it to each host, which defeats the
+purpose of build 4 since the analyst is the person who cannot deploy.
+Or asking the host at the moment of writing.
+
+## Decision
+
+**If the host's controller responds to `janela_frame_owner`, the
+engine assigns its return value as the owner of a frame it creates.**
+
+```ruby
+class ApplicationController < ActionController::Base
+  private
+    def janela_frame_owner
+      Current.account
+    end
+end
+```
+
+A host that defines nothing gets a nil owner, which is correct for a
+single tenant application and is what the demo did before it had
+tenancy at all.
+
+This is the pattern `policy_scope` already established (ADR 004):
+Janela asks the host's controller a question by duck typing, and takes
+silence as an answer rather than requiring configuration. It keeps
+Janela's settings at one, `parent_controller`, and it puts the
+decision in the only place that can make it, inside a request where
+the current user and tenant exist.
+
+**Janela still never interprets the owner.** It assigns what it is
+handed and reads nothing from it. Scoping remains entirely the host's
+policy, exactly as ADR 014 said.
+
+## Consequences
+
+- An analyst can create a dashboard and see it, which is the whole
+  point of build 4 and was impossible without this.
+- A multi tenant host that forgets to define the method gets frames
+  nobody can see. That is a quiet failure, so it is what the doctor
+  task should notice: a host with a `policy_scope` that filters frames
+  by owner, but no `janela_frame_owner`, is misconfigured. Worth
+  adding to ADR 015's checks.
+- Duck typing means a typo in the method name fails silently, which is
+  the cost of not having configuration. The doctor check above is the
+  mitigation.
+- The same question will arrive for any other record Janela writes on
+  a host's behalf. The answer is this pattern rather than a second
+  setting, and this ADR is the precedent to cite.

data/docs/decisions/020-formatting-belongs-to-the-measure.md

@@ -0,0 +1,93 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 002, ADR 009, ADR 012, ADR 018
+Triggers:
+  - a number rendering with more precision than it means
+  - adding an option to a pane, a frame or a pane URL
+  - units, currency or percentages
+  - a chart and a table showing the same number differently
+Topics: dsl, rendering, charts, snapshots, configuration
+---
+
+# ADR 020: Formatting Belongs to the Measure
+
+## Context
+
+An averaged measure rendered as `928.8767833333333`. Tables ran
+values through `number_with_delimiter`, which handles thousands and
+nothing else, and a chart tooltip showed whatever the database
+returned. Nothing anywhere said how many decimal places a number
+means, or that it is money, or a percentage.
+
+There are four layers that could say, and each was a real candidate.
+
+The **pane** is where an analyst works, so it is the tempting answer:
+this chart in thousands, that one to the cent. But a pane is a
+database row and a form field, so every knob there is a migration, a
+validation and another decision put to someone who should not have to
+know that `amount` is a decimal with a scale of two. Worse, the same
+measure on two frames could disagree about itself.
+
+The **pane URL** would make it ad hoc, `?precision=0`. That widens the
+grammar ADR 005 fixed, and it lets anyone holding a link change what a
+number appears to say. Precision is not a question a reader asks.
+
+The **frame** is the wrong shape. One frame holds panes from different
+models, so a single setting would be right for the currency and wrong
+for the count sitting next to it.
+
+The **measure** is the only one of the four that knows what the number
+*is*. The other three know where it appears.
+
+## Decision
+
+**A measure declares its own format, and every renderer asks the
+measure.**
+
+```ruby
+janela do
+  measure :revenue, sum: :amount, prefix: "$"
+  measure :pass_rate, average: :score, precision: 1, suffix: "%"
+  measure :orders, count: true
+end
+```
+
+**Almost nothing needs declaring, because the schema already knows.**
+Precision is the measure's own if it declares one, otherwise the
+column's: counting rows has no decimal places, a `decimal(10, 2)`
+column has two, summing an integer column stays whole. Only where
+neither says anything, such as averaging an integer, does it fall back
+to two places. Thousands are delimited with the host's own locale.
+
+`prefix` and `suffix` carry the unit, which no amount of rounding can
+say. They are two plain strings rather than a currency vocabulary,
+because a string is the thing a forker can read and replace in a
+minute.
+
+**Formatting is rendering, never rounding.** The number itself reaches
+a snapshot, an order clause and a comparison at full precision. A
+stored pane is data (ADR 009), so a snapshot taken last month reads
+back under a format declared today.
+
+**One formatter serves every renderer.** A table cell, a single value
+and a chart tooltip all show the string the measure produced, and the
+chart is handed those strings rather than formatting a second time in
+JavaScript. The chart still plots raw numbers, because an axis is a
+scale and not a label.
+
+## Consequences
+
+- The common measures read correctly with nothing declared, which is
+  the test this had to pass: money as money, counts as counts.
+- A host changes how every one of its numbers reads by editing its
+  model, not by touching a dashboard, a URL or a template.
+- A measure that wants two formats is two measures. That is a real
+  limit, and it is the same answer ADR 002 gives to every other
+  variation: declare what you mean and name it.
+- The chart controller now takes a `formatted` value alongside
+  `values`. A host that renders its own chart from Janela's data has
+  the strings available and is not obliged to use them.
+- If per pane formatting ever proves necessary, the measure's format
+  is the default it would override, not something to be undone first.
+  This is the layer to add it to, and the reason to think twice.

data/docs/decisions/021-a-check-has-a-name-a-host-can-silence.md

@@ -0,0 +1,84 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 010, ADR 015, ADR 019
+Triggers:
+  - adding a check to janela:doctor
+  - adding a setting to Janela
+  - a warning that is a false alarm for some applications
+  - running the doctor in CI
+Topics: configuration, tooling, upgrades, agent-guidance
+---
+
+# ADR 021: A Check Has a Name, and a Host Can Silence It
+
+## Context
+
+`janela:doctor` reports what a host still has to do, and one of its
+checks cannot be certain. Authentication is whatever the host does, so
+the check reads the controller's filters and says what it sees. For an
+application that authenticates another way, that warning is wrong
+every single run.
+
+A warning that is always wrong is worse than no warning. People learn
+to skip the output, and the next finding, the true one, goes unread
+with it. In CI it is worse again, because the only way to keep a green
+build is to stop running the task.
+
+The pattern here is settled elsewhere. Django's system check framework
+gives every check an identifier and lets a project list the ones to
+silence. Homebrew, Flutter, npm, Bundler and RubyGems all ship a
+doctor of some shape, and the mature ones can be told to be quiet
+about a thing the maintainer has already judged.
+
+Janela had neither half: findings were prose with no stable handle, so
+there was nothing to name in a conversation, a commit message or a
+setting.
+
+## Decision
+
+**Every finding carries the name of the check that produced it**, in
+the output and on the finding itself:
+
+```
+WARNING (unauthenticated-endpoints): no authentication filter found on ApplicationController
+```
+
+The name is the check's own method name, dasherised by the runner
+rather than written out per check, so a code and the thing it names
+cannot drift apart. Words rather than numbers: there are seven checks,
+not seven hundred, and `unmigrated-tables` needs no lookup table the
+way `janela.E004` would.
+
+**A host silences a check by that name**:
+
+```ruby
+# config/initializers/janela.rb
+Janela.silenced_checks = %w[unauthenticated-endpoints]
+```
+
+**A silenced check is named every run**, in one line at the end, even
+when there is nothing else to report. A silence nobody remembers is
+how a real finding goes unread, which is the problem this is meant to
+solve rather than reproduce.
+
+This is Janela's second setting, and deliberately so. ADR 019 turned
+down configuration for what owns a frame because ownership is
+per-request state that a setting cannot hold. Silencing is the
+opposite: a judgement made once, about the application as a whole,
+that does not change between requests. That is what configuration is
+for, and the distinction is the rule to apply next time rather than a
+preference about this one.
+
+## Consequences
+
+- The doctor can run in CI on an application it cannot fully
+  understand, which is the only way it gets run at all.
+- Silencing an error passes the task. That is the point and it is a
+  loaded gun, which is why the silence is printed every run.
+- A check's name is now public. Renaming a check method renames what a
+  host silences, so a rename is a breaking change and goes in
+  UPGRADING.md like any other (ADR 015).
+- Agents get a stable handle too. "Silence unmigrated-tables" is an
+  instruction that can be given and followed without quoting a
+  sentence of prose (ADR 010).

data/docs/decisions/INDEX.md

@@ -20,18 +20,23 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 
 | Topic | ADRs |
 |-------|------|
-| **Vision, scope, forkability** | 001, 010 |
+| **Vision, scope, forkability** | 001, 010, 012 |
 | **Open-source & host-decoupling** | 001 |
 | **DSL & query layer** | 002, 006, 007 |
-| **Dependencies** | 002, 003, 004, 006 |
-| **Authorisation** | 002, 003, 004, 009 |
+| **Dependencies** | 002, 003, 004, 006, 017 |
+| **Authorisation** | 002, 003, 004, 009, 017, 019 |
+| **Performance & storage** | 007, 017 |
 | **Cross-filtering & Hotwire** | 003, 004, 005, 008 |
-| **Layouts & views** | 011 |
+| **Layouts & views** | 011, 012, 016, 018 |
+| **CSS & styling** | 016, 018 |
+| **Frames, panes & persistence** | 012, 013, 014, 019 |
+| **Naming rule** | 014 |
 | **JavaScript delivery & charts** | 004, 006 |
 | **Time dimensions** | 006 |
-| **Routes, URLs & naming** | 005, 007, 008, 009, 011 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013 |
 | **Snapshots & publishing** | 009 |
-| **AI agents & guidance** | 010 |
+| **AI agents & guidance** | 010, 015 |
+| **Releases & upgrades** | 015 |
 | **Security** | 003 |
 | **Testing** | 003 |
 
@@ -50,7 +55,17 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 009 | Snapshots | 2026-09-15 | Accepted |
 | 010 | Agent Guidance Ships, the Agent Waits | 2026-09-15 | Accepted |
 | 011 | Panes Do Not Render in the Host Layout | 2026-09-15 | Accepted |
+| 012 | Frames and Panes Are Data | 2026-09-15 | Accepted |
+| 013 | Naming and Addressing Frames | 2026-09-15 | Accepted |
+| 014 | Corrections Before Frames Are Built | 2026-09-15 | Accepted |
+| 015 | How Breaking Change Is Communicated | 2026-09-16 | Accepted |
+| 016 | The Styling Vocabulary | 2026-09-16 | Accepted |
+| 017 | Janela Owns No Data Store | 2026-09-16 | Accepted |
+| 018 | A Table Is the Universal Renderer | 2026-09-16 | Accepted |
+| 019 | A Created Frame Asks the Host Who Owns It | 2026-09-16 | Accepted |
+| 020 | Formatting Belongs to the Measure | 2026-09-16 | Accepted |
+| 021 | A Check Has a Name, and a Host Can Silence It | 2026-09-16 | Accepted |
 
 ## Next number
 
-Next ADR: 012
+Next ADR: 022

data/docs/multi-tenancy.md

@@ -0,0 +1,175 @@
+# Fitting Janela into a multi tenant application
+
+Janela holds no tenancy of its own. There is no tenant setting, no
+default scope of ours on your models, and nothing to configure. The
+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 owns a frame being created? | `janela_frame_owner` on the same controller | Nothing: a nil owner |
+
+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
+rather than being configured: ownership is per-request state, and a
+setting cannot hold it.
+
+## What goes through your scope
+
+Everything. There is no path through the engine that reads a record
+without asking first:
+
+- The index of frames, and each frame page.
+- Every editing action on a frame or a pane, so another tenant's frame
+  is a 404 to rename or delete as much as to read.
+- Every pane's own query, on Janela's pages and inline in yours. The
+  measure is calculated over `policy_scope(Order)`, not over `Order`.
+- An ad hoc pane URL, which is the same query by another route.
+- A snapshot, read through `policy_scope(Janela::Snapshot)`.
+
+A pane rendered inline in your own page runs in your request, so the
+same scope applies there as in the engine's controllers. Nothing is
+calculated in a background context where the current tenant would have
+gone missing.
+
+## With Pundit
+
+Write a policy for Janela's own record. The class name is namespaced,
+because the model is:
+
+```ruby
+# app/policies/janela/frame_policy.rb
+module Janela
+  class FramePolicy < ApplicationPolicy
+    class Scope < ApplicationPolicy::Scope
+      def resolve
+        scope.where(owner: Current.account)
+      end
+    end
+  end
+end
+```
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Pundit::Authorization
+
+  private
+    def janela_frame_owner
+      Current.account
+    end
+end
+```
+
+Your own models keep the policies they already have. Janela calls
+`policy_scope(Order)` and gets whatever `OrderPolicy::Scope` returns.
+
+## With acts_as_tenant
+
+Your own models are already scoped, so the only thing Janela needs
+told about is its own tables. Define `policy_scope` as the adapter:
+
+```ruby
+class ApplicationController < ActionController::Base
+  set_current_tenant_through_filter
+  before_action :set_tenant
+
+  private
+    def policy_scope(model)
+      case model.name
+      when "Janela::Frame" then model.where(owner: ActsAsTenant.current_tenant)
+      else model.all # acts_as_tenant has already scoped your own models
+      end
+    end
+
+    def janela_frame_owner
+      ActsAsTenant.current_tenant
+    end
+end
+```
+
+## With CanCanCan, or with your own
+
+The same adapter, pointed at whatever you use:
+
+```ruby
+def policy_scope(model)
+  model.accessible_by(current_ability)
+end
+```
+
+Janela never asks how the answer was arrived at. A method that takes a
+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.
+
+## What owns a frame
+
+`Janela::Frame belongs_to :owner, polymorphic: true, optional: true`.
+It can point at an account, a team, a user or anything else you scope
+by, and Janela reads nothing from it. It exists so your scope has a
+column.
+
+Return the tenant from `janela_frame_owner` and the engine assigns it
+to a frame it creates. Skip that method while your scope filters by
+owner and the analyst's new dashboard is saved with no owner, then
+hidden by your own policy the instant it is saved. It looks like the
+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
+
+`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:
+
+- 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.
+
+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).
+
+## Proving your wiring
+
+Run the doctor first. It reads your application and reports the traps
+that are visible from outside a request:
+
+```bash
+bin/rails janela:doctor
+```
+
+Then write the test that matters, which is the one that fails if a
+scope is ever loosened. Create a frame as one tenant and ask for it as
+another:
+
+```ruby
+test "another tenant's frame is a 404" do
+  frame = Janela::Frame.create!(name: "Theirs", owner: accounts(:acme))
+
+  sign_in users(:globex_analyst)
+  get janela.frame_path(frame)
+
+  assert_response :not_found
+end
+```
+
+This repository's dummy application is a worked example of all of the
+above, in
+[test/dummy/app/controllers/application_controller.rb](https://github.com/retail-tasker/janela/blob/main/test/dummy/app/controllers/application_controller.rb),
+scoped by a `?tenant=` parameter standing in for a session.
+
+## What Janela will never do
+
+Add a tenant filter of its own. Your scope is the only one, so there
+is nothing to double filter and nothing that looks enforced while
+being unenforceable. Janela can be handed any relation through `on:`,
+so a guarantee made here would be a guarantee it cannot keep.

data/lib/janela/definition.rb

@@ -9,7 +9,7 @@ module Janela
     end
 
     def measure(name, **aggregate)
-      measures[name] = Measure.build(name, **aggregate).tap { |measure| reject_boolean_column!(measure) }
+      measures[name] = Measure.build(name, model: model, **aggregate).tap { |measure| reject_boolean_column!(measure) }
     end
 
     def dimension(name, through: nil, column: nil, granularity: nil)
@@ -44,6 +44,10 @@ module Janela
       dimensions.fetch(name) { raise NotFound, "#{model} has no janela dimension #{name.inspect}" }
     end
 
+    def measure!(name)
+      measures.fetch(name) { raise NotFound, "#{model} has no janela measure #{name.inspect}" }
+    end
+
     # ActiveRecord casts an aggregate back through the column's own type, so
     # AVG over a boolean returns true rather than a ratio. Say so at
     # declaration rather than rendering a meaningless pane.
@@ -91,9 +95,5 @@ module Janela
         raise BadRequest, "#{model} does not allow filtering on #{dropped.join(', ')}. " \
                      "Declare a janela dimension, or add it to ransackable_attributes."
       end
-
-      def measure!(name)
-        measures.fetch(name) { raise NotFound, "#{model} has no janela measure #{name.inspect}" }
-      end
   end
 end