janela 0.7.0 → 0.9.0

data/docs/decisions/038-a-ratio-is-a-measure-of-its-own.md

@@ -0,0 +1,194 @@
+---
+Date: 2026-09-24
+Status: Proposed
+Related: ADR 001, ADR 002, ADR 007, ADR 020, ADR 025
+Triggers:
+  - adding a measure kind, or a sixth aggregate to the DSL
+  - deciding how a measure's value is scaled or formatted
+  - changing how a grouped pane is ordered
+  - a host wanting a rate or a percentage over a boolean column
+  - wondering whether a measure option belongs on the measure or on a pane
+Topics: DSL, query layer, measures, formatting, ordering
+---
+
+# ADR 038: A Ratio Is a Measure of Its Own, Stored as a Fraction and Read as a Percentage
+
+## Context
+
+A boolean column is how an application stores a yes or no fact, and
+averaging one is how a person asks what share of rows are yes. Janela
+refuses that today, correctly, and the refusal leaves nowhere to go
+(#20, #27).
+
+Four things were measured against the demo on `c6922da`, Rails 8.1.3.1
+and SQLite, with `orders.expedited` as a real boolean column.
+
+**The cast is total, not partial.** `Order.average(:expedited)` returns
+`true` where the true ratio is `0.333`, and returns `true` again where
+the true ratio is `0.0`, because Rails' boolean cast does not read a
+float `0.0` as false. There is no value of the ratio that renders as
+anything other than `true`. #20 described this as a cast losing
+information; it loses all of it.
+
+**The existing machinery already carries the fix.**
+`relation.average(Arel.sql("CASE WHEN ... THEN 1.0 ELSE 0.0 END"))`
+answers `0.3333333333333333` as a Float ungrouped, and grouped it
+answers a hash per bucket. Nothing new is needed for grouping,
+gap filling, cross filtering or snapshots, because the ratio goes
+through the same `Measure#apply` every other measure goes through.
+
+**Ordering breaks, which #27 did not mention.** `Definition` orders a
+grouped query with `order(Arel.sql("#{measure.sql_alias} DESC"))`, and
+`sql_alias` is `"#{aggregate}_#{column}"`, the alias ADR 007 names.
+There is no such alias for an expression: the string becomes
+`average_CASE WHEN orders.expedited THEN 1.0 ELSE 0.0 END DESC` and
+raises `ActiveRecord::StatementInvalid`. Ordering by the expression
+itself works and sorts correctly.
+
+**The null claim in #27 is backwards.** On one true, one false and one
+null row:
+
+| expression | result |
+| --- | --- |
+| `AVG(CASE WHEN f THEN 1.0 ELSE 0.0 END)`, null as false | 0.333 |
+| the same with a `WHEN f IS NULL THEN NULL` arm | 0.5 |
+| `AVG(f)`, plain | 0.5 |
+
+#27 says excluding null "differs from `AVG` in SQL". Excluding null is
+exactly what `AVG` does. The naive `CASE` is the form that differs, and
+it counts every unknown as a failure, which is this library's worst
+failure mode: a wrong number that looks like a right one.
+
+### Fraction or percentage, and where that choice lives
+
+The formatter does not scale. `format(0.6667)` with `suffix: "%"`
+renders `"0.7%"`, wrong by a hundred; `format(66.67)` renders
+`"66.7%"`. ADR 020's own example, `measure :pass_rate, average: :score,
+precision: 1, suffix: "%"`, only reads correctly if the value is
+already on a nought to a hundred scale.
+
+Three positions were considered.
+
+**Storing nought to a hundred** was rejected. ADR 020 holds that the
+number itself reaches a snapshot, an order clause and a comparison at
+full precision. Storing a presentation scale puts a display choice into
+a frozen snapshot and into an `ORDER BY`, where it is no longer a
+display choice at all. A ratio is a proportion, and a proportion is
+nought to one.
+
+**Leaving the scale to each pane** was rejected, and ADR 020 had
+already rejected it: `janela_panes` carries `model`, `measure`,
+`dimension`, `renderer`, `granularity`, `limit` and `position`, and no
+formatting columns, deliberately. Two panes of one measure could
+otherwise freeze different numbers into different snapshots and serve
+both as fact. ADR 020's consequences say per pane formatting, if it
+ever arrives, overrides the measure's format rather than replacing the
+idea, and calls that the reason to think twice.
+
+**A fraction with an opt in percentage**, such as `percent: true` or a
+remembered `suffix: "%"`, was considered and is the option this
+decision narrows rather than takes. A proportion shown to a person is a
+percentage; making that a flag means every host that declares a rate
+also remembers a second thing, and a host that forgets gets `0.31` on a
+dashboard where `31.2%` was meant. ADR 001 prefers one obvious way over
+a knob.
+
+## Decision
+
+**A ratio is a measure kind of its own. It computes a fraction, and it
+renders as a percentage.**
+
+```ruby
+janela do
+  measure :expedited_rate, ratio: :expedited   # a boolean column
+end
+```
+
+**The kind sits beside the five aggregates rather than inside them.**
+ADR 002 says a measure takes exactly one aggregate of `sum`, `count`,
+`average`, `minimum`, `maximum`. `ratio:` is a sixth option in that
+position and not a sixth aggregate, because it names a column and an
+intent rather than an SQL function. `Measure::AGGREGATES` is unchanged
+and the error a host already sees when it declares two of them is
+unchanged.
+
+**It requires a boolean column, which is the mirror of the refusal it
+answers.** `average:` rejects a boolean column and names `ratio:`;
+`ratio:` rejects anything that is not one. Both look the column up
+through `model.type_for_attribute`, so the expression is built from a
+column the model has confirmed, never from a string that arrived over
+HTTP. ADR 025 bounds what a filter may ask for; this is the same
+principle one layer down.
+
+**Null is excluded, so a ratio agrees with `AVG`.**
+
+```sql
+AVG(CASE WHEN col IS NULL THEN NULL WHEN col THEN 1.0 ELSE 0.0 END)
+```
+
+An unknown is not a failure. A host that wants unknowns counted as
+failures says so in its own schema with a `NOT NULL` default, which is
+a decision about the data rather than about the dashboard.
+
+**A condition form is not included.** `ratio: { status: "paid" }` was
+considered and rejected: it is a second query language growing inside
+the measure, it needs the same bounding ADR 025 gives filters, and the
+case it serves is already served. Where a column is not already a yes
+or no fact, the split is the honest answer and cross filters better,
+which is what #20's refusal says and what ADR 002 says to every other
+variation. The boolean case earns its own kind precisely because the
+split cannot answer it: "the share that passed, over time" is one
+series, and a dimension gives two.
+
+**The stored number is the fraction. The rendered string is the
+percentage.** The value that reaches a snapshot, an `ORDER BY`, a chart
+axis and a comparison is `0.3119`. The string a table cell, a single
+value and a chart tooltip show is `31.2%`. This follows ADR 020 rather
+than bending it: that decision forbids transforming the number, and a
+ratio's number is never transformed. Only the string is.
+
+Precision defaults to one decimal place for a ratio rather than ADR
+020's fallback of two, because a percentage carries two more significant
+figures than the fraction it came from and `31.19%` is noise. A measure
+may still declare its own.
+
+**Declaring `prefix:` or `suffix:` on a ratio raises.** The kind already
+says what unit it is, and a host that writes `suffix: "%"` out of habit
+would otherwise render `31.2%%`. Raising names the conflict rather than
+guessing which was meant, which is what this library does everywhere
+else it is given two answers.
+
+**A measure answers what it is ordered by, rather than what its column
+alias is.** `Measure#sql_alias` becomes `Measure#order_by`: for an
+aggregate it returns the alias ActiveRecord already gives, unchanged,
+and for a ratio it returns the `AVG(CASE ...)` expression. ADR 007's
+decision is untouched, since a category pane is still ordered by its
+measure, largest first, with no way to turn it off. Only the mechanism
+it named has to widen, because that ADR assumed every measure is an
+aggregate with an alias and a ratio is not.
+
+## Consequences
+
+- A host with a boolean column declares one line and gets a rate that
+  cross filters, gap fills, snapshots and orders like any other measure.
+- `rails janela:doctor` has nothing to add. The declaration either
+  raises at boot or is correct, so there is no silent state for a check
+  to find.
+- **A measure that wants the fraction rather than the percentage cannot
+  have it.** That is the cost of refusing the flag, and it is a real
+  one: a host wanting `0.31` on a dashboard has to use `average:` over
+  a numeric column of its own. If that turns up in practice, the answer
+  is a format on the measure, not on the pane, and ADR 020 already says
+  which layer that is.
+- `Measure#sql_alias` is gone. It is internal rather than documented
+  surface, with one call site in the gem, but a fork that reached for it
+  will not find it, so it needs a line in `CHANGELOG.md` under Changed
+  rather than an `UPGRADING.md` step (ADR 015): nothing a host declares
+  changes.
+- #20's error message names `ratio:`, which closes the loop the refusal
+  opened. That string is what a host actually meets, so it is part of
+  the work rather than a nicety.
+- What would change this decision: a host that needs a rate over
+  something that is not a boolean column and for which the split is
+  genuinely wrong. That is the case the condition form was rejected for,
+  and one real report of it is better evidence than the argument above.

data/docs/decisions/039-a-pane-can-hold-words-and-only-code-writes-markup.md

@@ -0,0 +1,168 @@
+---
+Date: 2026-09-24
+Status: Accepted
+Related: ADR 001, ADR 009, ADR 012, ADR 016, ADR 036, ADR 037
+Triggers:
+  - putting a heading, a paragraph, a link, an icon or an image on a stored frame
+  - adding a kind of pane that is not a query
+  - letting an analyst's text reach a page
+  - storing HTML, Markdown or a template in a row
+  - deciding whether a frame draws its own name
+Topics: frames, panes, persistence, layout, authorisation, html
+---
+
+# ADR 039: A Pane Can Hold Words, and Only Code Writes Markup
+
+## Context
+
+ADR 012 made a dashboard data so that its author, the analyst, can
+change it without a deploy. It gave the analyst one thing to arrange:
+a pane that names a measure the model declared. That was the whole
+vocabulary, and it is why a stored frame is safe to hand over. A row
+cannot invent a query, reach a model nobody exposed, or put anything on
+the page that a developer did not write.
+
+A real dashboard is more than query results. The first one a host asked
+about had, above its numbers, a heading with an icon, a count of done
+out of total, a percentage, a "view all" link and a progress bar. A
+block form frame can have all of it, because the page around the panes
+is the host's own ERB (docs/composing.md). A stored frame can have none
+of it. `janela/frames/_frame` renders `frame.panes` and nothing else,
+and `Janela::Pane` requires a `measure` and validates it against a
+`janela` block, so there is no row a heading could be. The frame's
+`name` is never drawn either. The analyst who owns the dashboard can
+choose every number on it and cannot label them.
+
+So the question is not whether a stored frame should hold content. It
+has to, or the frame the analyst owns is always the unlabelled half of
+the page. The question is what an analyst may put in a row without
+breaking the property ADR 012 was built on.
+
+### What was considered
+
+**Stored HTML**, a column of markup rendered as it is, was rejected.
+It is the one thing ADR 012 exists to prevent: an analyst's row would
+put arbitrary markup on a page that every other reader of that frame
+loads, which is stored cross site scripting with a dashboard for a
+delivery mechanism. Running it through Rails' `sanitize` narrows the
+tags but not the problem. The allowlist becomes a security boundary
+Janela has to maintain, and what survives it, links anywhere and
+styling that imitates the host's own chrome, is still content a
+developer did not write appearing as if they had.
+
+**Markdown** was rejected for the same reason one step removed. It
+compiles to HTML, it needs a parser as a dependency (ADR 001 is spare
+with those), and a link in it can point anywhere. What an analyst
+actually needs from it, a heading and a paragraph, is two fields.
+
+**A sandboxed iframe**, `<iframe srcdoc sandbox="allow-scripts">`, was
+considered because an application built on this gem already renders
+agent-authored slides that way, and it works: the sandbox gives the
+content an opaque origin, so it cannot read the page or its cookies.
+It was rejected for a public gem. The surface is large, the
+guarantees depend on attributes a host can loosen, and an iframe does
+not size to its content, so it cannot sit in a CSS grid beside a pane
+without fixed heights, which is exactly what #24 is trying to remove
+for charts. It stays available to any host that wants it, in its own
+code, around a frame.
+
+**Drawing the frame's name as a heading** was rejected as the whole
+answer. It would change every existing frame's appearance on upgrade,
+it gives one heading per frame when a dashboard often wants one per
+row, and it still leaves no icon, no paragraph and no link.
+
+**A separate table of content rows** beside `janela_panes` was
+rejected because position is the frame's single ordering. Two tables
+would need a shared position sequence across them, and ADR 012 kept
+one level between a frame and what it shows on purpose.
+
+## Decision
+
+**A pane can hold words instead of a query. An analyst writes text
+into a row and Janela escapes it; anything that needs markup is a
+partial the host wrote in code, which the analyst places by name.**
+
+This is ADR 012's division of labour applied to content: developers
+define what can be shown, analysts arrange it and write the words.
+
+**A pane gains a `kind`.** `query` is today's pane and the default, so
+every existing row is unchanged. Two more kinds:
+
+- **`text`**: a `heading`, a `body` and an optional `link`, each a
+  plain string. Janela renders the heading as a heading, the body as
+  paragraphs split on blank lines, and the link as an anchor, and
+  escapes all three. No markup an analyst types reaches the page as
+  markup.
+- **`partial`**: a `partial` name, plus the same `heading`, `body` and
+  `link` passed to it as locals. The partial is the host's, under
+  `app/views/janela_content/`, so the host writes the icon, the image,
+  the layout and the look, and the analyst writes the words that go in
+  it. A name must match `/\A[a-z0-9_]+\z/` and a partial must exist in
+  that directory, so a row cannot reach any other template. There is
+  no registry and no setting: the directory is the allowlist, the way
+  a controller's views directory already is. It sits outside
+  `app/views/janela/` on purpose. A host view at an engine's path
+  replaces the engine's own, and `janela/panes/` already holds the
+  engine's `_form` and `_row`, so a content partial named `form` there
+  would silently replace the pane editing form.
+
+```ruby
+frame.panes.create!(kind: "text", heading: "Refunds are excluded",
+                    body: "Figures are in the store's own currency.")
+frame.panes.create!(kind: "partial", partial: "overview_heading",
+                    heading: "Project overview", link: "/cards", span: 3)
+```
+
+A `text` or `partial` pane has no `model` or `measure`. Those columns
+become nullable, and a validation requires them for `query` and
+refuses them for the other two, so the database cannot hold a
+half-query.
+
+**A link is a path, not a URL.** `link` must start with `/`, and not
+`//`, so an analyst can point readers at another page of the same
+application and cannot send them to another site. A host that wants an
+external link writes it in a partial.
+
+**Images and icons are the host's.** Janela stores no files and ships
+no icon set (ADR 036). A heading with an icon is a partial that draws
+the icon beside the heading it is given. An image is a partial that
+reads it from wherever the host already keeps images. Janela does not
+take a dependency on Active Storage to do something a host's own
+partial already can.
+
+**A content pane sits in the grid like any other.** It spans columns,
+it is ordered by `position`, it is drawn as a `janela-pane`, and under
+vitral it is a pane of glass. It does not take part in cross filtering:
+it has no query, so the frame controller has no `src` to rewrite, and a
+content pane renders inline rather than inside a turbo frame.
+
+## Consequences
+
+- An analyst can label a stored frame, explain it and link out of it
+  without a deploy, which is the half of ADR 012 that was missing.
+- The property ADR 012 stated plainly still holds, extended: a row can
+  name only a declared measure, an escaped string, a same-site path, or
+  a partial a developer wrote. Nothing an analyst types is markup.
+- `janela_panes` gains `kind`, `heading`, `body`, `link` and `partial`,
+  and `model` and `measure` become nullable. That is a migration a host
+  has to install, so it needs an `UPGRADING.md` entry (ADR 015). The
+  engine's own forms need a way to add each kind.
+- The pane partial becomes a branch on `kind`. `_pane.html.erb` is the
+  smallest file this touches and should stay that way: one partial per
+  kind under `janela/frames/`, chosen by name.
+- Snapshots store results, not HTML (ADR 009). A snapshot is a list of
+  pane results with no frame behind it, so a content pane has no result
+  to store and is not in one. Words that explain a signed off figure
+  have to live in whatever page shows the snapshot. If a snapshot ever
+  needs to carry the text that sat beside its numbers on the day, that
+  is a separate decision.
+- The pane class names a theme may target (ADR 036) gain one for the
+  content kinds, `janela-content`, and it goes into docs/theming.md in
+  the same change.
+- Not in 1.0 (ADR 037). It adds to the public surface rather than
+  changing it, so it does not block a stable release and can land
+  before or after one.
+- What would change this decision: a host that genuinely needs an
+  analyst to author markup, with a real reason a partial cannot serve.
+  The sandboxed iframe is the fallback that case would reopen, and this
+  record says why it was set aside.

data/docs/decisions/040-a-host-can-fix-a-frames-filter.md

@@ -0,0 +1,145 @@
+---
+Date: 2026-09-24
+Status: Accepted
+Related: ADR 003, ADR 008, ADR 012, ADR 024, ADR 025, ADR 030, ADR 032, ADR 034
+Triggers:
+  - showing a frame on a record's own page, filtered to that record
+  - reusing one frame across many records
+  - carrying a host's filter in q[...] and finding it cleared
+  - deciding whether a filter is a view choice or an authorisation boundary
+  - changing how a pane URL is built, or what clear() and toggle() touch
+Topics: frames, filters, cross-filtering, urls, authorisation
+---
+
+# ADR 040: A Host Can Fix a Frame's Filter, and No Click Removes It
+
+## Context
+
+A host wants the same dashboard on every record's page, narrowed to
+that record: a frame of the work in a queue, shown at the top of each
+queue's page. Since ADR 012 a frame is a row an analyst edits, so the
+panes are the same everywhere and only the record changes. Janela has
+no way to say "this frame, for this record" (#57).
+
+The only filter Janela knows is the one in the page URL, `q[...]`
+(ADR 008). So a host redirects the record's page to carry one,
+`/queues/42?q[queue_id_eq]=42`, and the panes read it. Measured on the
+demo with `q[status_eq]=paid` standing in for the host's filter, it
+does not hold:
+
+- Opened with the filter, the revenue pane read $469,097.85 and every
+  pane's `src` carried `q[status_eq]=paid`.
+- **Clear filters**, the button a dashboard shows, took it off. Revenue
+  read $664,639.01, the whole table, and the page URL lost the
+  parameter.
+- **Escape**, with focus inside the frame, did the same.
+- A click on a `status` value would replace it, because `toggle()`
+  clears every predicate on the dimension it is changing (ADR 024).
+
+None of this is a bug in the frame controller. `q[...]` is Janela's by
+design: `stripFilters` removes every `q[` key before writing the
+current selection, and `clear()` empties the frame's filters, because
+the selection is the reader's to change. A host's filter placed there
+becomes the reader's to change too. On a record's page the reader then
+sees every record their scope allows under that record's heading.
+Nothing leaks, since `policy_scope` still bounds every pane (ADR 032).
+The numbers are wrong, and they look right.
+
+### What was considered
+
+**Making `clear()` leave the host's keys alone** was rejected. The
+controller cannot tell a host's `q[queue_id_eq]` from a reader's link
+that carries the same key, and ADR 008 means a shared link carries
+exactly that. Any rule for telling them apart would be a second
+convention inside one parameter.
+
+**The host's `policy_scope`** was rejected. It answers who may see
+which rows, and it runs in the engine's pane requests, which know
+nothing about the page that holds the frame. Putting a page's record
+into it would make authorisation depend on which page a pane was
+loaded from, and ADR 032's checks would be reasoning about a scope that
+changes per page.
+
+**Storing the filter on the frame**, a `filters` column on
+`janela_frames`, was rejected as the answer to this case. The case is
+one frame reused across many records, so the filter belongs to the
+render, not to the row. A frame that should always be narrowed the
+same way is a smaller, different case, and it can be built on this
+later.
+
+**Signing the filter**, carrying it as a `MessageVerifier` token so a
+reader cannot edit it, was rejected. It would imply a security
+guarantee this is not. A reader who edits the fixed filter out of a
+pane URL sees rows `policy_scope` already lets them see, which they
+could see on any other dashboard. Signing adds a key to rotate and a
+failure mode to explain, to protect nothing that authorisation does
+not already protect.
+
+## Decision
+
+**A host passes a filter when it renders a frame, and Janela applies it
+to every pane beneath the reader's selection, where no click, clear or
+link can remove it.**
+
+```erb
+<%= janela_frame @frame, where: { queue_id_eq: @queue.id } %>
+
+<%= janela_frame where: { queue_id_eq: @queue.id } do %>
+  <%= janela_pane Card, :count, by: :status %>
+<% end %>
+```
+
+`where:` is the name `Definition#query` already uses for the same
+thing, Ransack conditions narrowing a relation, so a host learns one
+word for it.
+
+**It travels in the pane's base URL under its own key, `where[...]`.**
+The helper writes it into each pane's `data-janela-src`, the base the
+frame controller builds every request from, and into the first
+render's `src`. The controller never reads or writes `where[...]`:
+`stripFilters` removes only `q[` keys, `clear()` empties only the
+frame's filters, and `toggle()` changes only `q[`. So the fixed filter
+survives every click without the controller learning anything about
+it. It is not written into the page URL, which already says what the
+record is.
+
+**The server applies it first and separately.** The pane endpoints
+read `params[:where]` and `params[:q]` and narrow the relation twice,
+fixed filter first, so the reader's selection can only narrow further.
+The same key in both is two conditions ANDed, never one replacing the
+other. The fixed filter goes through `Definition#filter`, so it is
+bounded exactly as `q[...]` is: only declared dimensions, only the
+predicates ADR 025 allows for each kind, and no more than 1000 values.
+A host cannot fix a filter on a column it has not declared, which is
+the same rule a reader already meets.
+
+**It is a view filter, not an authorisation boundary, and the
+documentation says so in those words.** It is visible in every pane's
+URL, and a reader can remove it by editing one. What they reach by
+doing that is what `policy_scope` already allows. A host that needs a
+reader not to see other records writes that in its scope, where it
+applies to every pane on every page.
+
+## Consequences
+
+- One frame serves every record's page. An analyst edits it once, and
+  the host needs no column pointing at a frame per record.
+- A host that carries its filter in `q[...]` today, by redirect, moves
+  it to `where:` and drops the redirect. Nothing breaks if it does not
+  move; the old way keeps its old weakness. The guide for this goes in
+  docs/composing.md.
+- The pane URL shape gains `where[...]`. ADR 037 names the pane URL as
+  part of the surface that stops moving at 1.0, so this is better
+  decided before 1.0 than after, and it is additive: every existing URL
+  means what it meant.
+- A snapshot is taken with the filters its caller passes (ADR 009,
+  ADR 034), not from a rendered page. A host snapshotting a record's
+  frame passes the fixed filter in `filters:`, and nothing does that
+  for it. Worth a line in the snapshot documentation, not a mechanism.
+- The dimension the host fixes should not also be offered as a
+  clickable pane. Clicking it would AND a second condition on the same
+  column, and any value but the fixed one returns nothing. That is
+  correct and confusing, so the guide says not to.
+- What would change this decision: a host that needs the fixed filter
+  hidden from the reader for a reason `policy_scope` cannot express.
+  That would reopen signing, and this record says why it was left out.

data/docs/decisions/041-a-host-finds-its-frame-by-owner-and-key.md

@@ -0,0 +1,112 @@
+---
+Date: 2026-09-24
+Status: Accepted
+Related: ADR 012, ADR 013, ADR 014, ADR 019, ADR 040
+Triggers:
+  - giving a record of the host's its own frame
+  - finding a frame from code without storing its id
+  - an owner that has more than one frame
+  - adding a slug, a handle or any second identifier to a frame
+Topics: frames, persistence, naming, host-integration
+---
+
+# ADR 041: A Host Finds Its Frame by Owner and Key
+
+## Context
+
+A host that shows a frame on one of its own pages has to find that
+frame from code. ADR 012 made frames rows an analyst edits, and ADR 040
+made one frame usable across many records, so the host needs a way to
+say "the frame for this" without a deploy creating it and without
+remembering an id.
+
+The owner looked like the answer. It is a nullable polymorphic
+reference that Janela never reads (ADR 014, ADR 019), so a host can
+point it at the record the frame is for, and
+`Janela::Frame.find_or_create_by!(owner: queue)` is a frame's `dom_id`:
+two columns, nothing added to the host's schema.
+
+It holds for exactly one frame per owner, and owners rarely have one. A
+tenant owns every frame an analyst makes from the engine's New button,
+through `janela_frame_owner`, and a host wants frames of its own for
+particular pages on top of those. `find_by(owner: account)` then returns
+whichever row the database gives first. On a real installation it
+returned the wrong frame: the first the tenant had ever made, not the
+one the page was for (#59).
+
+### What was considered
+
+**`name` as the key** was rejected. It is the analyst's to rename, so a
+host looking a frame up by name loses it the day someone edits the
+title.
+
+**A column in the host's table** pointing at the frame was rejected as
+the answer the owner was meant to save a host from. It needs a
+migration on every table whose records want a frame, and a second one
+for each extra frame per record.
+
+**A slug**, which ADR 013 turned down, is not what is being asked for,
+and the difference is the reason this is allowed. ADR 013 rejected a
+slug as a way to *address* a frame: in a URL a person reads, derived
+from the name, needing uniqueness rules, reserved words and regeneration
+on rename, and a second lookup path to keep working. What a host needs
+is none of those. It is an identifier the host writes in its own code,
+never in a URL, never derived from the name, never shown to an analyst,
+and never changed once set.
+
+**Janela choosing the frame for a record**, a registry mapping host
+classes to frames, was rejected as configuration for something one line
+of the host's code already says.
+
+## Decision
+
+**A frame may carry a `key` the host sets. A frame is found by its
+owner and its key together, and each owner has at most one frame per
+key.**
+
+```ruby
+Janela::Frame.for(account, :overview)         # the tenant's overview
+Janela::Frame.for(queue, :analytics)          # this queue's frame
+Janela::Frame.for(queue, :analytics) { |frame| frame.name = "#{queue.name} analytics" }
+```
+
+`for` finds the frame with that owner and key, or creates it. The block
+runs only when it creates one, to set what the host wants a new frame to
+start as; a new frame is named after its key unless the block says
+otherwise. The owner may be `nil` for a host with one tenant.
+
+**The key is the host's and nobody else's.** Janela reads it only in
+`for`. It is not in any route and not in the engine's forms, so an
+analyst can rename, regrid and recompose a keyed frame without being
+able to detach it from the page that finds it. A frame without a key,
+which is every frame an analyst makes, is unchanged.
+
+**Uniqueness is per owner, in the database.** A unique index on owner
+and key, so two requests creating the same frame at once end with one
+row, and `for` retries the find when the insert loses that race. Frames
+with no key are not constrained by it.
+
+`key` is a short lowercase string matching `/\A[a-z0-9_]+\z/`, the
+shape of the symbols a host will pass, so `:analytics` and `"analytics"`
+are the same key and nothing that looks like a URL or a name gets in.
+
+## Consequences
+
+- A host gives any record any number of frames with no column of its
+  own: owner and key are the `dom_id`, and the key is the suffix
+  `dom_id(queue, :analytics)` would carry.
+- `janela_frames` gains `key` and a unique index, so a migration and an
+  `UPGRADING.md` entry (ADR 015). Existing frames keep a nil key.
+- The owner now does two jobs for a host that uses `for`: tenancy for
+  the policy scope, and which record a frame belongs to. ADR 019 said
+  Janela never reads the owner; `for` queries by it, and only there. A
+  host whose owner is a record rather than its tenant has to make its
+  policy scope see frames owned by its own records, which the
+  multi-tenancy guide shows.
+- A frame deleted from the engine's pages is created again, empty, the
+  next time its page is visited. That is the right answer for a frame a
+  page depends on, and it is worth a line in the README so it is not a
+  surprise.
+- What would change this decision: a host needing to find a frame by
+  something that is not stable in its own code. That is the addressing
+  problem ADR 013 decided, and it would be decided there again.