docs(adr): virtual categories and measures are defined by criteria, never declared (improvise-cq1q.1)

Their ids and displays are hardcoded; an old file's _Measure names are
recognised, not migrated as declarations. Open question 2 narrows to
where a new-version file declares the stored measures.

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:39:23 -07:00
committed by Edward Langley
parent 209270542c
commit 4778d9741b
+28 -22
View File
@@ -19,7 +19,7 @@ amendment is approved:
| clause | accepted rule | the amendment proposes |
|---|---|---|
| 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`) |
| 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`; virtual categories and measures are defined by criteria with hardcoded ids and displays, are never declared in a file, and are referred to by 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 |
@@ -102,13 +102,18 @@ the reservation needs no check in the grammar.
- **[Amendment] Virtual ids are lower case.** The code, the wire, `ViewState` and the
browser client spell the virtual categories `_Index`, `_Dim` and `_Measure` today,
and move to the lower-case ids in the re-key step (clause 11).
- **[Amendment] A file never declares a virtual category; it refers to one by its
id.** The virtual categories exist in every document, so they are not required in
the file. Where a line refers to one, it spells the virtual id:
`_measure: column`, `_index: none`, `region=east, _measure=revenue = 1200`. An
old-version file's `_Measure` resolves through its display at load, like every name
in an old file (clause 5), and the first save writes `_measure`. Where the file
declares the stored measures themselves (`Revenue`, `Cost`) is open question 2.
- **[Amendment] Virtual categories and virtual measures are defined by criteria, not
declared.** Each contains whatever in the document meets its criterion: `_measure`
holds the measures, and `_index` and `_dim` hold the record positions. Their ids and
displays are hardcoded in the application, so a file never declares one. Where a
line refers to one, it spells the virtual id: `_measure: column`, `_index: none`,
`region=east, _measure=revenue = 1200`.
- **[Amendment] An old file's virtual names are recognised, not migrated as
declarations.** The loader recognises `_Measure`, `_Index` and `_Dim` by their
hardcoded displays, and an old `## Category: _Measure` section is read for the
stored measures it lists, not as a declaration of `_measure`. The first save writes
`_measure` wherever the file refers to it. Where a new-version file declares the
stored measures themselves (`Revenue`, `Cost`) is open question 2.
- **[Amendment] Records mode's synthetic positions are values, not ids.** The row
coordinate under `_index` is a value of that virtual category. So, by the same
reasoning, is the column coordinate under `_dim` (a column index, gotcha 1). They are
@@ -803,29 +808,30 @@ which contradicts clause 1.
### 2. Where does a file declare the stored measures?
**The question.** A file never declares a virtual category (clause 1). But the stored
measures, such as `Revenue` and `Cost`, are items of `_measure`, and each needs a
declaration that carries its display and id. Today they are listed under
`## Category: _Measure`:
**The question.** `_measure` is never declared: it holds whatever meets its criterion,
and its id and display are hardcoded (clause 1). But the stored measures in it, such as
`Revenue` and `Cost`, are ordinary things with a user's display and a generated id, so
the file must declare each one. Today they are listed under the virtual category's own
header, which a new-version file no longer writes:
```
## Category: _Measure
- Revenue, Cost
```
**Why it matters.** Without a declaration a measure has no display or id in the file,
and a new-version file refuses any undeclared id (clause 5).
**Why it matters.** Without a declaration a stored measure has no display or id in the
file, and a new-version file refuses any undeclared id (clause 5). The declaration is
also what puts a stored measure into `_measure`'s criterion.
**Options.**
- **(a) Keep a section for the virtual category's items only**, spelled by its id:
`## Category: _measure` with `- Revenue(revenue), Cost(cost)`. The section declares
items, not the category.
- **(b) A dedicated section**, such as `## Measures`, with the same item lines.
- **(c) Declare a measure where it is first used**, in a data key. A data key holds
only an id, so the display would be lost.
- **(a) A dedicated section**, such as `## Measures`, with item lines
(`- Revenue(revenue), Cost(cost)`). Being declared there is what makes something a
stored measure.
- **(b) A marker on an ordinary item line**, wherever the measure is listed, for
example `- Revenue(revenue) [measure]`.
**Author's recommendation:** (b). It names what the section holds, and keeps the
virtual category out of the file entirely.
**Author's recommendation:** (a). It names what the section holds, and keeps the
virtual category's header out of the file.
### 3. Does interactive typing still resolve a display name that matches no id?