Docs update

Author: CrushBy

docs/rules/en/Rules.md

@@ -244,13 +244,15 @@ D. FEEDBACK / REPORTING (`lsfusion_report_feedback`)
 
 4. An expression whose comma is NOT enclosed in brackets of
    its own — `OVERRIDE a, b`, `CONCAT sep, a, b`,
-   `GROUP CONCAT expr, sep` — MUST NOT go straight into a
-   comma-separated list (`PROPERTIES`, `EXPORT FROM`,
-   `JSON FROM`, `ORDER`, group-object and parameter lists):
-   that comma reads as the list separator and the list
-   silently reshapes. Group it, or name it as a property, in
-   whichever form the enclosing block accepts. A comma inside
-   an ordinary call's own parentheses is safe.
+   `GROUP CONCAT expr, sep`, `MAX a, b` — MUST NOT go
+   straight into a comma-separated list (`PROPERTIES`,
+   `EXPORT FROM`, `JSON FROM`, `ORDER`, group-object and
+   parameter lists): that comma reads as the list separator
+   and the list silently reshapes. Group it, or name it as
+   a property, in whichever form the enclosing block accepts.
+   A call's own commas — `f(a, b)` — are safe in the enclosing
+   list, but they do not fence off such an expression placed
+   inside them: `f(MAX a, b)` passes one argument, not two.
 
 5. When introducing a new parameter, the assistant MUST
    declare its class explicitly at the first use

docs/rules/en/Rules_logic.md

@@ -164,7 +164,42 @@ title: 'Rules: domain logic'
     silently drops the fractional part;
     the correct form is `NUMERIC[16,4](a) * b / c`.
 
-17. A parameter's class annotation (`prop(SubClass x)`) is a
+17. The class of an expression's result can be wider than
+    the classes it is built from, and the assistant MUST
+    account for that wherever a narrower class is required —
+    above all in a `+=` implementation, where it is
+    a server startup error.
+
+    Arithmetic widens further than it looks:
+
+    - `+` and `-` — like `MIN` / `MAX` and the selection
+      operators — take the common ancestor, widening the
+      whole part and the scale independently, so the result
+      can be wider than either operand:
+      `NUMERIC[16,2] + NUMERIC[10,4]` is `NUMERIC[18,4]`;
+    - `*` adds both the whole parts and the scales:
+      `NUMERIC[16,2] * NUMERIC[10,4]` is `NUMERIC[26,6]`;
+    - `/` widens catastrophically: with the default settings
+      its scale is always the maximum `NUMERIC` scale (`32`),
+      so `NUMERIC[16,2] / NUMERIC[16,2]` is `NUMERIC[48,32]`.
+
+    A `GROUP` aggregate mostly keeps the class of what it
+    aggregates — a `GROUP SUM`, `GROUP MAX` or `GROUP LAST`
+    over a `NUMERIC[16,2]` is `NUMERIC[16,2]` — but it
+    carries outward whatever that expression already widened
+    to. `GROUP CONCAT` is the aggregate that widens by
+    itself: its result is a string of unlimited length.
+    String concatenation widens as well, summing the
+    operands' lengths: `ISTRING[200] + ISTRING[126]`
+    is `ISTRING[326]`.
+
+    A narrower class is obtained only by an explicit cast of
+    the whole expression. With operands of integer classes
+    the operand cast of rule 16 does not bound the result —
+    the division still widens to scale `32` — so both casts
+    are needed: `NUMERIC[16,2](NUMERIC[16,2](a(x)) / b(x))`.
+
+18. A parameter's class annotation (`prop(SubClass x)`) is a
     signature, not a runtime filter: it resolves same-named
     properties and sets the signature, but the computed set is
     determined by the properties used in the expression.
@@ -176,7 +211,7 @@ title: 'Rules: domain logic'
     an explicit `x IS SubClass` condition (or use a property
     declared on that subclass).
 
-18. In the `GROUP ... BY` operator the assistant MUST NOT
+19. In the `GROUP ... BY` operator the assistant MUST NOT
     list in the `BY` block the upper parameters used
     in the operator's expressions: each such parameter
     is already implicitly a group — a parameter of the
@@ -187,7 +222,7 @@ title: 'Rules: domain logic'
     to the parameters not used in the expressions;
     a mismatch in count or classes is an error.
 
-19. `MAX` and `MIN` are prefix operators over a comma-separated
+20. `MAX` and `MIN` are prefix operators over a comma-separated
     operand list (`MAX a, b`), not infix ones: `a MAX b`
     does not parse — the platform reports
     `no viable alternative at input 'MAX'`.
@@ -212,42 +247,13 @@ title: 'Rules: domain logic'
    `specified` and `expected` lines name the implementation's
    class and the declared one.
 
-   Arithmetic is what widens the class most often, and it
-   widens further than it looks:
-
-   - `+` and `-` — like `MIN` / `MAX` and the selection
-     operators — take the common ancestor, widening the whole
-     part and the scale independently, so the result can be
-     wider than either operand:
-     `NUMERIC[16,2] + NUMERIC[10,4]` is `NUMERIC[18,4]`;
-   - `*` adds both the whole parts and the scales:
-     `NUMERIC[16,2] * NUMERIC[10,4]` is `NUMERIC[26,6]`;
-   - `/` widens catastrophically: with the default settings
-     its scale is always the maximum `NUMERIC` scale (`32`),
-     so `NUMERIC[16,2] / NUMERIC[16,2]` is `NUMERIC[48,32]`.
-
-   A `GROUP` aggregate mostly keeps the class of what it
-   aggregates — a `GROUP SUM`, `GROUP MAX` or `GROUP LAST`
-   over a `NUMERIC[16,2]` is `NUMERIC[16,2]` — but it carries
-   outward whatever that expression already widened to.
-   `GROUP CONCAT` is the aggregate that widens by itself: its
-   result is a string of unlimited length (`ISTRING` against
-   a declared `ISTRING[250]`). Plain string concatenation
-   widens as well, summing the operands' lengths
-   (`ISTRING[326]` against a declared `ISTRING[250]`).
-
-   Any such expression the assistant MUST wrap in an explicit
+   An expression that widens the value class — arithmetic
+   above all, and division most of all (rule 17 of the
+   property rules) — the assistant MUST wrap in an explicit
    cast to the declared class:
    `f(X x) += NUMERIC[16,2](a(x) / b(x));`
    `f(X x) += ISTRING[250](a(x) + b(x));`
 
-   For operands of integer classes the cast MUST go on an
-   operand first, so that the division is not integer
-   division (see rule 16 of the property rules); the result
-   still widens to scale `32` like any other division, so
-   the outer cast is needed as well:
-   `f(X x) += NUMERIC[16,2](NUMERIC[16,2](a(x)) / b(x));`
-
 ### Ordering rules (`ORDER`)
 
 1. Where two rows can share an order key and the answer depends

docs/rules/ru/Rules.md

@@ -248,14 +248,17 @@ D. ОБРАТНАЯ СВЯЗЬ / ОТЧЁТЫ (`lsfusion_report_feedback`)
    строкового литерала в lsFusion и НЕ ДОЛЖНЫ использоваться.
 
 4. Выражение, чья запятая НЕ заключена в собственные скобки —
-   `OVERRIDE a, b`, `CONCAT sep, a, b`, `GROUP CONCAT expr, sep` —
-   НЕ ДОЛЖНО попадать прямо в список с разделением запятыми
-   (`PROPERTIES`, `EXPORT FROM`, `JSON FROM`, `ORDER`, списки
-   групп объектов и параметров): эта запятая читается как
-   разделитель списка, и список молча перекраивается.
+   `OVERRIDE a, b`, `CONCAT sep, a, b`, `GROUP CONCAT expr, sep`,
+   `MAX a, b` — НЕ ДОЛЖНО попадать прямо в список
+   с разделением запятыми (`PROPERTIES`, `EXPORT FROM`,
+   `JSON FROM`, `ORDER`, списки групп объектов и параметров):
+   эта запятая читается как разделитель списка,
+   и список молча перекраивается.
    Сгруппируйте его или назовите свойством — той формой, какую
-   принимает внешний блок. Запятая внутри собственных скобок
-   обычного вызова безопасна.
+   принимает внешний блок. Собственные запятые вызова —
+   `f(a, b)` — во внешнем списке безопасны, но не отгораживают
+   такое выражение, помещённое внутрь них: `f(MAX a, b)`
+   передаёт один аргумент, а не два.
 
 5. Вводя новый параметр, ассистент ОБЯЗАН задавать его
    класс явно при первом использовании (`prop(Class x)`,

docs/rules/ru/Rules_logic.md

@@ -163,7 +163,42 @@ title: 'Rules: domain logic'
     молча отбрасывает дробную часть;
     правильная форма — `NUMERIC[16,4](a) * b / c`.
 
-17. Класс в объявлении параметра (`prop(SubClass x)`) — это
+17. Класс результата выражения может оказаться шире классов,
+    из которых оно построено, и ассистент ОБЯЗАН учитывать
+    это везде, где требуется более узкий класс, — прежде
+    всего в реализации `+=`, где это ошибка старта сервера.
+
+    Арифметика расширяет класс сильнее, чем кажется:
+
+    - `+` и `-` — как `MIN` / `MAX` и операторы выбора —
+      дают общего предка, расширяя целую часть и шкалу
+      независимо, поэтому результат может оказаться шире
+      любого из операндов:
+      `NUMERIC[16,2] + NUMERIC[10,4]` — это `NUMERIC[18,4]`;
+    - `*` складывает и целые части, и шкалы:
+      `NUMERIC[16,2] * NUMERIC[10,4]` — это `NUMERIC[26,6]`;
+    - `/` расширяет катастрофически: при настройках
+      по умолчанию его шкала всегда равна максимальной шкале
+      `NUMERIC` (`32`), поэтому
+      `NUMERIC[16,2] / NUMERIC[16,2]` — это `NUMERIC[48,32]`.
+
+    Агрегат `GROUP` в основном сохраняет класс того, что
+    агрегирует, — `GROUP SUM`, `GROUP MAX` или `GROUP LAST`
+    по `NUMERIC[16,2]` дают `NUMERIC[16,2]`, — но выносит
+    наружу то, до чего расширилось агрегируемое выражение.
+    Сам по себе расширяет `GROUP CONCAT`: его результат —
+    строка неограниченной длины. Конкатенация строк тоже
+    расширяет, складывая длины операндов:
+    `ISTRING[200] + ISTRING[126]` — это `ISTRING[326]`.
+
+    Более узкий класс получается только явным приведением
+    всего выражения. Для операндов целочисленных классов
+    приведение операнда из правила 16 не ограничивает
+    результат (деление всё равно расширяется до шкалы `32`),
+    поэтому нужны оба приведения:
+    `NUMERIC[16,2](NUMERIC[16,2](a(x)) / b(x))`.
+
+18. Класс в объявлении параметра (`prop(SubClass x)`) — это
     сигнатура, а не фильтр времени выполнения: он разрешает
     одноимённые свойства и задаёт сигнатуру, но вычисляемое
     множество определяется свойствами, использованными
@@ -176,7 +211,7 @@ title: 'Rules: domain logic'
     добавить явное условие `x IS SubClass` (или использовать
     свойство, объявленное на этом классе-потомке).
 
-18. В операторе `GROUP ... BY` ассистент НЕ ДОЛЖЕН
+19. В операторе `GROUP ... BY` ассистент НЕ ДОЛЖЕН
     перечислять в блоке `BY` верхние параметры,
     использованные в выражениях оператора: каждый такой
     параметр уже неявно является группировкой — параметром
@@ -188,7 +223,7 @@ title: 'Rules: domain logic'
     не использованные в выражениях; несовпадение
     количества или классов даёт ошибку.
 
-19. `MAX` и `MIN` — префиксные операторы над списком
+20. `MAX` и `MIN` — префиксные операторы над списком
     операндов через запятую (`MAX a, b`), а не инфиксные:
     `a MAX b` не разбирается — платформа выдаёт
     `no viable alternative at input 'MAX'`.
@@ -214,43 +249,13 @@ title: 'Rules: domain logic'
    `specified` и `expected` которой указаны класс реализации
    и объявленный класс.
 
-   Чаще всего класс расширяет арифметика, причём сильнее,
-   чем кажется:
-
-   - `+` и `-` — как `MIN` / `MAX` и операторы выбора —
-     дают общего предка, расширяя целую часть и шкалу
-     независимо, поэтому результат может оказаться шире
-     любого из операндов:
-     `NUMERIC[16,2] + NUMERIC[10,4]` — это `NUMERIC[18,4]`;
-   - `*` складывает и целые части, и шкалы:
-     `NUMERIC[16,2] * NUMERIC[10,4]` — это `NUMERIC[26,6]`;
-   - `/` расширяет катастрофически: при настройках
-     по умолчанию его шкала всегда равна максимальной
-     шкале `NUMERIC` (`32`), поэтому
-     `NUMERIC[16,2] / NUMERIC[16,2]` — это `NUMERIC[48,32]`.
-
-   Агрегат `GROUP` в основном сохраняет класс того, что
-   агрегирует, — `GROUP SUM`, `GROUP MAX` или `GROUP LAST`
-   по `NUMERIC[16,2]` дают `NUMERIC[16,2]`, — но выносит
-   наружу то, до чего расширилось агрегируемое выражение.
-   Сам по себе расширяет `GROUP CONCAT`: его результат —
-   строка неограниченной длины (`ISTRING` при объявленном
-   `ISTRING[250]`). Обычная конкатенация строк тоже
-   расширяет, складывая длины операндов (`ISTRING[326]`
-   при объявленном `ISTRING[250]`).
-
-   Любое такое выражение ассистент ОБЯЗАН обернуть в явное
-   приведение к объявленному классу:
+   Выражение, расширяющее класс значения, — прежде всего
+   арифметику, и в первую очередь деление (правило 17 правил
+   свойств), — ассистент ОБЯЗАН обернуть в явное приведение
+   к объявленному классу:
    `f(X x) += NUMERIC[16,2](a(x) / b(x));`
    `f(X x) += ISTRING[250](a(x) + b(x));`
 
-   Для операндов целочисленных классов приведение ОБЯЗАНО
-   сначала стоять на операнде, чтобы деление не оказалось
-   целочисленным (см. правило 16 правил свойств); результат
-   при этом всё равно расширяется до шкалы `32`, как любое
-   деление, поэтому внешнее приведение тоже нужно:
-   `f(X x) += NUMERIC[16,2](NUMERIC[16,2](a(x)) / b(x));`
-
 ### Правила упорядочивания (`ORDER`)
 
 1. Там, где две строки могут разделить ключ порядка, а ответ