docs(adr): a formula never merges into a stored measure; it takes profit-<n> (improvise-cq1q.1)

Clause 1 states it, with what removal leaves. Open question 1 is
replaced by the residue: two measures then share a display, which
clause 2's uniqueness rule forbids.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
This commit is contained in:
Claude (adr007-steward)
2026-10-09 09:38:06 -07:00
committed by Edward Langley
parent ccc6751886
commit 209270542c
+29 -23
View File
@@ -21,6 +21,7 @@ amendment is approved:
| 1 | groups have no id | a group has an id and a display, and its id behaves like every other id |
| 1 | `_index`, `_dim`, `_measure` are the only ids beginning with `_` | a leading `_` is reserved for virtual ids in general, including the virtual views `_records` and `_drill`; a file never declares a virtual category and refers to one by its id (`_measure`) |
| 2 | `CellKey` pairs are `(CategoryId, ItemId)` | `(CategoryId, ItemHandle)` |
| 1 | (silent; today `measure_item_names` merges a formula into a stored measure of the same name) | a formula never merges: it gets its own id, `profit-<n>` beside a stored `profit` |
| 2, 5 | a collapsed entry and a group reference name a group by name | by its id |
| 4 | casefold; a run of U+0020 spaces becomes one `_`; strip characters outside `a`–`z`, `0`–`9`, `-`, `_`; remove a leading `_` | casefold; every character outside `a`–`z`, `0`–`9` and `-` becomes `_`; runs of `_` collapse; leading and trailing `_` and `-` are removed; `n` is prepended to a slug that starts with a digit |
| 5 | a hand-written id uses the alphabet `a`–`z`, `0`–`9`, `-`, `_` and may begin with `_` only if reserved | a hand-written id obeys every syntax rule of a generated id |
@@ -126,10 +127,16 @@ one, for a derived dimension.
formula refers to it as `profit`, each Profit cell's `CellKey` holds `profit` under
`_measure`, and `ReplaceFormula` and `RemoveFormula` address `profit`.
- **[Amendment] Each measure's cells are keyed by one handle.** A stored measure is
keyed `ItemHandle::Item(id)`. A measure that exists only through its formula is
keyed `ItemHandle::FormulaTarget(id)`. The id is the measure's either way, and no
column is keyed by both. What happens when a formula's measure and a stored measure
share a display, and what removing that formula does, is open question 1.
keyed `ItemHandle::Item(id)`. A formula's measure is keyed
`ItemHandle::FormulaTarget(id)`. The id is the measure's either way, and no column is
keyed by both.
- **[Amendment] A formula never merges into a stored measure.** If a stored measure
`profit` (displayed `Profit`) exists and the user adds `Profit = Revenue - Cost`,
the new formula is a second measure with a fresh id, `profit-<n>` from the shared
counter (clause 4), like any colliding generated id. The stored measure keeps
`profit` and its data. Removing the formula removes `profit-<n>` and leaves `profit`
untouched. Both are displayed `Profit`, which clause 2's display-uniqueness rule
does not allow; open question 1 asks how that is resolved.
- **[Amendment] A target outside `_Measure` is a real item**, with its own `ItemId`,
and its formula has a separate `FormulaId`. A formula whose generated id would
collide takes a suffix like any other generated id (clause 4): a formula `Tax` in
@@ -176,7 +183,9 @@ human-typed name resolves to exactly one id within its scope, and a rename to a
display already in use there is refused. An item's scope is its category, so two
categories may each have an item displayed `Revenue`. Formula text crosses
categories, so a display may be ambiguous there. The ids differ, so the formula panel
shows the ids where a display is ambiguous.
shows the ids where a display is ambiguous. **[Amendment]** A formula and a stored
measure may end up sharing a display (clause 1); whether that is an exception to this
rule is open question 1.
### 3. Ids are interned symbols
@@ -771,29 +780,26 @@ three things:
These are open, and nothing above depends on an answer except where it says so.
### 1. A formula and a stored measure with the same display: one measure, and what does removal do?
### 1. Two measures with the same display: is that allowed?
**The question.** A document stores a `Profit` measure: an item of `_measure` with id
`profit`, display `Profit`, holding data. The user then adds the formula
`Profit = Revenue - Cost`. A formula is a kind of measure with one id (clause 1), and
displays are unique within their scope (clause 2), so this cannot simply make a second
`Profit`. Today `measure_item_names` merges the two into one column.
**The question.** A formula never merges into a stored measure (clause 1): with a stored
`Profit` (id `profit`) in the document, adding the formula `Profit = Revenue - Cost`
creates a second measure, `profit-1`. Both are displayed `Profit`. But clause 2 keeps
displays unique within their scope, and both measures are in `_measure`'s scope.
**Why it matters.** It decides which handle keys the column (`Item(profit)` or
`FormulaTarget(profit)`, clause 1), what `RemoveFormula` leaves behind, and whether
documents that rely on today's merge keep loading.
**Why it matters.** Under the uniqueness rule, adding that formula would be refused,
which contradicts clause 1.
**Options.**
- **(a) The formula attaches to the stored measure.** One measure, id `profit`, keyed
`Item(profit)`; the formula computes it. Removing the formula leaves the stored
measure and its data.
- **(b) Refuse it.** Adding a formula whose display is a stored measure's is refused,
as any duplicate display is. Existing files that hold both must be repaired at load.
- **(c) The formula replaces the stored measure.** Its stored data is dropped or kept
hidden.
- **(a) Allow duplicate displays among measures only.** The formula panel already
shows ids wherever a display is ambiguous (clause 6), and typing prefers ids
(clause 12), so the two stay distinguishable.
- **(b) Drop display uniqueness everywhere.** Ids carry identity, and every place that
shows displays already falls back to ids when they clash.
- **(c) Keep uniqueness and give the new formula a different display**, such as
`Profit 1`, chosen by the host.
**Author's recommendation:** (a). It keeps today's behaviour, so existing documents
load unchanged, and a measure stays one thing with one id.
**Author's recommendation:** (a). It is the smallest change that makes clause 1 hold.
### 2. Where does a file declare the stored measures?