@rsconcept/rstool 0.2.1 → 0.4.0

package/docs/DIAGNOSTICS.md

@@ -1,130 +1,85 @@
-# Diagnostics reference
-
-Use this when an `analyzeExpression` / `addOrUpdateConstituenta` call returns errors in `result.diagnostics`.
-
-## How to read a diagnostic
-
-Each `DiagnosticRecord` carries:
-
-- `code` — numeric `RSErrorCode` (see table). The high nibble identifies the class (`0x82xx` lexer, `0x84xx` parser, `0x88xx` semantic, `0x81xx` runtime, `0x28xx` warnings).
-- `params` — substitution arguments for the message (identifier names, sets, etc.).
-- `from`, `to` — character positions in the _expression text_ that should be patched. Always edit `definitionFormal` by range.
-- `constituentId` — present in session diagnostics from `listDiagnostics`.
-
-Resolve `code` from **`@rsconcept/domain`** (installed: `node_modules/@rsconcept/domain/src/rslang/error.ts`):
-
-- **`RSErrorCode`** — reverse-lookup the numeric value to its symbol name (`missingParenthesis`, `globalNotTyped`, …). The identifier is the canonical error kind; inline comments on each member document the hex id.
-- **`getRSErrorPrefix(code)`** — short label with class + hex (`P8406`, `S8803`, …).
-- **`params`** — substitution arguments from the reporter (see `*.test.ts` cases in `domain/src/rslang/` for examples per code).
-- **Tables below** — typical causes and agent fixes when patching `definitionFormal`.
-
-## Class table
-
-| Mask            | Class                | Behaviour                                                                      |
-| --------------- | -------------------- | ------------------------------------------------------------------------------ |
-| `0x8400` family | Parser               | Lexical / syntactic problems; expression cannot be analysed further            |
-| `0x8800` family | Semantic             | Definition-level issues (types, scopes, structure)                             |
-| `0x8100` family | Runtime / evaluation | Raised during `evaluateExpression` / `evaluateConstituenta`                    |
-| `0x2800` family | Warning              | Not critical; expression still valid                                           |
-| `0x88Cx`        | Schema-level         | Rules enforced by the schema layer (`cstEmptyDerived`, `definitionNotAllowed`) |
-
-`isCritical(code)` returns `false` only for `localDoubleDeclare` and `localNotUsed`.
-
-## High-priority codes
-
-### Parser
-
-| Code     | Symbol                 | Typical cause                        | Agent fix                       |
-| -------- | ---------------------- | ------------------------------------ | ------------------------------- |
-| `0x8400` | `unknownSyntax`        | Stray token / typo                   | Re-tokenise around `from`–`to`  |
-| `0x8406` | `missingParenthesis`   | Unmatched `(` `)`                    | Insert matching paren near `to` |
-| `0x8407` | `missingCurlyBrace`    | Unmatched `{` `}`                    | Insert matching brace           |
-| `0x8408` | `missingSquareBracket` | Unmatched `[` `]`                    | Insert matching bracket         |
-| `0x8409` | `bracketMismatch`      | Mixed bracket types                  | Replace one bracket to match    |
-| `0x840A` | `doubleParenthesis`    | `(( ... ))` redundancy               | Remove one pair                 |
-| `0x840B` | `missingOpenBracket`   | Closing bracket without opener       | Insert opening bracket earlier  |
-| `0x8415` | `expectedLocal`        | Quantifier or filter expects a local | Provide a lowercase variable    |
-| `0x8416` | `expectedType`         | Missing typification annotation      | Add explicit grade              |
-
-### Semantic — locals and scopes
-
-| Code     | Symbol               | Typical cause                    | Agent fix                       |
-| -------- | -------------------- | -------------------------------- | ------------------------------- |
-| `0x8801` | `localUndeclared`    | Variable used before declaration | Bind via quantifier / parameter |
-| `0x8802` | `localShadowing`     | Local redeclared in inner scope  | Rename inner variable           |
-| `0x8815` | `localOutOfScope`    | Local escapes its binder         | Move usage inside the binder    |
-| `0x2801` | `localDoubleDeclare` | Same local declared twice        | Warning; rename                 |
-| `0x2802` | `localNotUsed`       | Declared local never referenced  | Warning; remove or use          |
-
-### Semantic — types
-
-| Code     | Symbol                          | Typical cause                                          | Agent fix                                           |
-| -------- | ------------------------------- | ------------------------------------------------------ | --------------------------------------------------- |
-| `0x8803` | `typesNotEqual`                 | Operands have different typifications                  | Convert / project to matching grade                 |
-| `0x8804` | `globalNotTyped`                | Referenced global has no typification                  | Ensure dependency is upserted and typechecked first |
-| `0x8805` | `invalidDecart`                 | Cartesian product on non-set operand                   | Wrap operand in `ℬ(...)` if appropriate             |
-| `0x8806` | `invalidBoolean`                | `ℬ(...)` applied to a non-set                          | Use a set-grade operand                             |
-| `0x8807` | `invalidTypeOperation`          | Operator not defined for these types                   | Re-check the typification table                     |
-| `0x8808` | `invalidCard`                   | `card(...)` on a non-set                               | Use a set operand                                   |
-| `0x8809` | `invalidDebool`                 | `debool(...)` on non-singleton                         | Ensure exactly one element first                    |
-| `0x880B` | `globalFuncWithoutArgs`         | Calling a function without `[]` args                   | Provide arguments                                   |
-| `0x8810` | `invalidReduce`                 | `red(...)` on something not `ℬ(ℬ(...))`                | Wrap in extra `ℬ` or change source                  |
-| `0x8811` | `invalidProjectionTuple`        | `pr_i((a,b))` with out-of-range index                  | Use valid index                                     |
-| `0x8812` | `invalidProjectionSet`          | `Pr_i(S)` on non-tuple set                             | Use a tuple-set source                              |
-| `0x8813` | `invalidEnumeration`            | `{a, b}` with incompatible element types               | Match element typifications                         |
-| `0x8814` | `invalidCortegeDeclare`         | Tuple declaration with mismatched arity                | Match declaration to use                            |
-| `0x8816` | `invalidElementPredicate`       | `ξ ∈ S` typification mismatch                          | Match `ξ`'s grade to elements of `S`                |
-| `0x8817` | `invalidEmptySetUsage`          | `∅` in a position that needs a concrete element        | Provide explicit typified operand                   |
-| `0x8818` | `invalidArgsArity`              | Wrong number of arguments to function                  | Match function declaration                          |
-| `0x8819` | `invalidArgumentType`           | Argument typification mismatch                         | Adjust caller or function signature                 |
-| `0x881C` | `globalStructure`               | Wrong structural shape of referenced global            | Re-check `structure` constituent shape              |
-| `0x8821` | `radicalUsage`                  | Radical used outside parameter domain                  | Move usage into parameter declarations              |
-| `0x8822` | `invalidFilterArgumentType`     | `Fi[D](S)` parameter does not match index typification | Match `D` to projected grade                        |
-| `0x8823` | `invalidFilterArity`            | Filter parameter count ≠ multi-index length            | Align lengths                                       |
-| `0x8824` | `arithmeticNotSupported`        | Arithmetic operator outside integer context            | Use integer expressions                             |
-| `0x8825` | `typesNotCompatible`            | Generic type incompatibility                           | Re-examine surrounding context                      |
-| `0x8826` | `orderingNotSupported`          | `<`, `≤` etc. used outside integer                     | Ensure operands are integers                        |
-| `0x8827` | `expectedLogic`                 | Definition where `Logic` is required                   | Wrap in logical expression or change `cstType`      |
-| `0x8828` | `expectedSetexpr`               | Definition where STE required                          | Convert from logic to set expression                |
-| `0x8829` | `invalidArgumentCortegeDeclare` | Tuple parameter declaration mismatch                   | Match tuple arity in declaration                    |
-
-### Schema / cstType validation
-
-| Code     | Symbol                 | Trigger                                                | Fix                                                    |
-| -------- | ---------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
-| `0x8861` | `cstEmptyDerived`      | Derived constituent with empty `definitionFormal`      | Provide a definition                                   |
-| `0x8862` | `definitionNotAllowed` | `basic`/`constant` with non-empty formal               | Clear the formal                                       |
-| `0x8840` | `globalNoValue`        | Reference to global without a model value              | Set value via `setConstituentaValue` before evaluating |
-| `0x8841` | `invalidPropertyUsage` | Property-only constituent used where value is required | Use a different operand                                |
-
-### Runtime (evaluation)
-
-| Code     | Symbol                    | Cause                                    |
-| -------- | ------------------------- | ---------------------------------------- |
-| `0x8100` | `calcUnknownError`        | Unspecified evaluation failure           |
-| `0x8101` | `setOverflow`             | Intermediate set too large               |
-| `0x8102` | `booleanBaseLimit`        | `ℬ(X)` overflow at runtime               |
-| `0x8103` | `calcGlobalMissing`       | Referenced global has no current value   |
-| `0x8104` | `iterationsLimit`         | Iterative computation exceeded limit     |
-| `0x8105` | `calcInvalidDebool`       | `debool` on multi-element set at runtime |
-| `0x8106` | `iterateInfinity`         | Iteration over an infinite set           |
-| `0x8107` | `calculationNotSupported` | Construct cannot be evaluated            |
-
-## Common agent mistakes
-
-- **Setting a value on a derived constituent**: derived `term`, `axiom`, `statement` are inferrable. Use `evaluateConstituenta` / `recalculateModel`. Setting them throws `Constituent <alias> is inferrable and cannot be set directly`.
-- **Forgetting empty formal on `basic` / `constant`**: results in `definitionNotAllowed`. Pass `definitionFormal: ''`.
-- **Out-of-order dependencies**: referencing `D2` before upserting it raises `localUndeclared` or `globalNotTyped`. Always topologically sort.
-- **Wrong cstType for the role**: `axiom`/`statement` whose definition is not `Logic` raises `expectedLogic`. A `term` whose body is logical raises `expectedSetexpr`.
-- **Negative literals**: `-5` does not parse. Use `0 - 5`.
-- **Radicals in result expressions**: `[α∈R1] (α, R1)` raises `radicalUsage`. Use radicals only in parameter domains.
-- **Evaluating before bindings are set**: `evaluateExpression` referencing `X1` without a `setConstituentaValue(..., target: <X1.id>)` raises `calcGlobalMissing` (`0x8103`).
-
-## Diagnostics loop
-
-1. Run `analyzeExpression` on a scratch.
-2. If `analysis.success === false`, iterate `analysis.diagnostics`.
-3. For each diagnostic: read `code`, `from`, `to`, and `params`. Look up `code` in `RSErrorCode` (`error.ts`) and use `getRSErrorPrefix` if you need a display id.
-4. Patch `definitionFormal` based on the range — never blindly retry without changing the input.
-5. Re-send. Repeat until success.
-6. Only then call `addOrUpdateConstituenta` to commit the constituent into the session.
+# Диагностика
+
+Читай, когда `analyzeExpression` или `addOrUpdateConstituenta` вернули `diagnostics`.
+
+## `DiagnosticRecord`
+
+- `code` — числовой `RSErrorCode`.
+- `params` — аргументы сообщения.
+- `from`, `to` — диапазон в `definitionFormal`.
+- `constituentId` — есть в диагностике сессии из `listDiagnostics`.
+
+Источник истины: `@rsconcept/domain/src/rslang/error.ts`. Для короткого вида UI/логов используй `getRSErrorPrefix(code)`.
+
+## Классы кодов
+
+- `0x8400` — parser: синтаксис и скобки.
+- `0x8800` — semantic: типизации, области видимости, структура.
+- `0x8100` — runtime/evaluation: вычисление модели.
+- `0x2800` — warning: обычно не блокирует выражение.
+- `0x88Cx` — правила схемы и `cstType`.
+
+## Частые parser-коды
+
+- `0x8400 unknownSyntax` — неопределенная синтаксическая ошибка.
+- `0x8406 missingParenthesis` — не закрыты `(` `)`.
+- `0x8407 missingCurlyBrace` — не закрыты `{` `}`.
+- `0x8408 missingSquareBracket` — не закрыты `[` `]`.
+- `0x8409 bracketMismatch` — смешаны типы скобок.
+- `0x840A doubleParenthesis` — лишняя пара скобок.
+- `0x840B missingOpenBracket` — закрывающая скобка без открывающей.
+- `0x8415 expectedLocal` — нужна локальная переменная.
+- `0x8416 expectedType` — нужна явная ступень.
+
+## Локальные переменные
+
+- `0x8801 localUndeclared` — свяжи переменную квантором или параметром.
+- `0x8802 localShadowing` — переименуй внутреннюю переменную.
+- `0x8815 localOutOfScope` — перенеси использование внутрь области видимости.
+- `0x2801 localDoubleDeclare` — warning; объявление задублировано.
+- `0x2802 localNotUsed` — warning; переменная не используется.
+
+## Типизации и структура
+
+- `0x8803 typesNotEqual` / `0x8825 typesNotCompatible` — операнды несовместимы.
+- `0x8804 globalNotTyped` — сначала добавь и проанализируй поставщика.
+- `0x8805 invalidDecart`, `0x8806 invalidBoolean`, `0x8810 invalidReduce` — неверная ступень для операции.
+- `0x8808 invalidCard` — `card(...)` не над множеством.
+- `0x8809 invalidDebool` — нет гарантии синглетона.
+- `0x880B globalFuncWithoutArgs` — функция вызвана без `[]`.
+- `0x8811 invalidProjectionTuple`, `0x8812 invalidProjectionSet` — неверная проекция.
+- `0x8813 invalidEnumeration` — элементы перечисления разных ступеней.
+- `0x8816 invalidElementPredicate` — `ξ ∈ S` с несовместимыми ступенями.
+- `0x8818 invalidArgsArity`, `0x8819 invalidArgumentType` — неверный вызов функции.
+- `0x8821 radicalUsage` — радикал вне домена параметра.
+- `0x8822 invalidFilterArgumentType`, `0x8823 invalidFilterArity` — неверный `Fi`.
+- `0x8824 arithmeticNotSupported`, `0x8826 orderingNotSupported` — нужна ступень `Z`.
+- `0x8827 expectedLogic` — нужна логическая формула.
+- `0x8828 expectedSetexpr` — нужно теоретико-множественное выражение, а не логика.
+
+## Схема и вычисление
+
+- `0x8861 cstEmptyDerived` — у выводимой конституенты пустая формула.
+- `0x8862 definitionNotAllowed` — у `basic`/`constant` непустая формула.
+- `0x8840 globalNoValue` / `0x8103 calcGlobalMissing` — нет значения в модели.
+- `0x8841 invalidPropertyUsage` — `Property` использован как вычислимое значение.
+- `0x8101 setOverflow`, `0x8102 booleanBaseLimit`, `0x8104 iterationsLimit` — выражение слишком дорого вычислять.
+- `0x8105 calcInvalidDebool` — `debool` получил не синглетон.
+- `0x8106 iterateInfinity`, `0x8107 calculationNotSupported` — конструкция не исполнима в конечной модели.
+
+## Типичные ошибки агентов
+
+- Задавать значение `term`/`axiom`/`statement` напрямую.
+- Писать формулу у `basic` или `constant`.
+- Добавлять потребителя раньше поставщика.
+- Давать логическое тело `term` или нелогическое тело `axiom`/`statement`.
+- Использовать `R#` в теле результата.
+- Вычислять производные понятия до привязки данных для базовых.
+
+## Цикл исправления
+
+1. Запусти `analyzeExpression`.
+2. Прочитай `code`, `from`, `to`, `params`.
+3. Исправь именно диапазон в `definitionFormal`.
+4. Не повторяй вызов без изменения ввода.
+5. После успеха вызывай `addOrUpdateConstituenta`.

package/docs/DOMAIN.md

@@ -1,91 +1,68 @@
-# Domain reference
-
-Compact English distillation of the canonical Russian domain glossary (`CONTEXT.md`). Read this first if you are an agent unfamiliar with the Concept Portal vocabulary.
-
-## Core concepts
-
-- **Subject domain** — a sphere of human activity that requires coordination and communication.
-- **Conceptual schema (`КС`)** — a formal system of definitions for a subject domain, made of constituents.
-- **Conceptual model (`РСМодель`)** — a pairing of a conceptual schema with an interpretation in concrete data.
-- **Operations Synthesis Schema (`ОСС`)** — a graph of load and synthesis operations that drives schema construction and evolution.
-- **RS language (`родоструктурная экспликация`)** — the formal genus-structure language used to define concepts, relations and operations inside a schema.
-- **Typification** — the computable structural type of a constituent's formal definition; the formal constraint on admissible interpretations.
-- **Term graph** — a directed dependency graph over constituents; an edge means "constituent A appears in constituent B's definition".
-
-## Constituents
-
-A **constituent** is the atomic building block of a conceptual schema. Each constituent may carry a term, a convention, a typification, a formal definition, a textual interpretation, and a comment. By role, a constituent is either undefined, derived, or a statement.
-
-Constituent aliases follow a strict prefix scheme:
-
-| Alias prefix | Role                                     | Notes                                                                                           |
-| ------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `N#`         | Nominoid                                 | Free vocabulary item, no formal definition                                                      |
-| `X#`         | Base set                                 | Undefined concept, set of elements                                                              |
-| `C#`         | Constant set                             | Undefined concept, set of elements, allows arithmetic predicates and operations                 |
-| `S#`         | Structured concept (**genus structure**) | Undefined concept; `definitionFormal` gives **typification**; meaning via `convention` / axioms |
-| `D#`         | Term                                     | Derived concept; `definitionFormal` is the **definition**; value computed in a model            |
-| `F#`         | Term-function                            | Parameterised derived concept yielding an STE                                                   |
-| `P#`         | Predicate-function                       | Parameterised derived concept yielding a logical expression                                     |
-| `A#`         | Axiom                                    | Logical statement asserting requirements                                                        |
-| `T#`         | Statement                                | Logical assertion about the model                                                               |
-| `R#`         | Radical                                  | Template placeholder for arbitrary typification                                                 |
-
-**Undefined concepts** (`X#`, `C#`, `S#`) are introduced by conventions (and optional axioms). For `S#`, the formal field states **typification** (the grade of elements), not a defining construction. **Derived concepts** (`D#`, `F#`, `P#`, `A#`, `T#`) carry a formal **definition** and must follow declaration order — every referenced constituent must already exist; their model values are obtained by evaluation.
-
-**Structure vs term:** `S#` with `ℬ(X1×X1)` declares “elements are pairs over `X1`”; the actual pairs come from interpretation. `D#` with `X1×X1` as the whole expression denotes the **full Cartesian product** (all pairs), which is a computed set — use `S#` + projections when modeling a relation.
-
-A **crucial constituent** is marked as content-bearing for filtering / focus; it has no semantic effect on the formal calculus.
-
-## Statuses
-
-Each constituent has one of the following correctness statuses:
-
-| Status       | Meaning                                                            |
-| ------------ | ------------------------------------------------------------------ |
-| Unknown      | Not yet validated                                                  |
-| OK           | Validated as correct                                               |
-| Error        | Validation failed                                                  |
-| Property     | Defines a non-computable set; only membership tests are admissible |
-| Incalculable | Cannot be evaluated directly (e.g. expected exponential blow-up)   |
-
-## RSModel evaluation states
-
-In a conceptual model each item has one of the following evaluation statuses:
-
-| Status              | Meaning                                         |
-| ------------------- | ----------------------------------------------- |
-| `NO_EVAL` (1)       | Not evaluated (definition is not interpretable) |
-| `NOT_PROCESSED` (2) | Interpretation has not been computed yet        |
-| `INVALID_DATA` (3)  | Provided data is invalid                        |
-| `EVAL_FAIL` (4)     | Evaluation raised an error                      |
-| `AXIOM_FALSE` (5)   | Axiom evaluated to FALSE                        |
-| `EMPTY` (6)         | Result is the empty set                         |
-| `HAS_DATA` (7)      | Interpretation computed and non-empty           |
-
-## Synthesis and OSS
-
-- **Load operation** attaches an existing schema to the OSS graph.
-- **Synthesis operation** combines operand schemas via an **identification table** (pairs of constituents to be treated as equivalent) and produces a result schema with **inherited constituents**.
-- **Cross-cutting changes** propagate edits from a **source constituent** to its **inherited constituents** through the OSS. Inherited constituents are not edited directly.
-- **Diamond synthesis** uses operand schemas with shared ancestors.
-- **Concept block** is a nominal grouping of schemas inside the OSS.
-
-## Relationships
-
-- A conceptual schema **contains** many constituents.
-- A conceptual model **interprets** exactly one schema at a given state.
-- An OSS **contains** load and synthesis operations.
-- A synthesis operation **consumes** one or more input schemas plus an identification table and **produces** a result schema with inherited constituents.
-- Cross-cutting changes **propagate** from a source constituent to its inherited descendants.
-- The term graph is **derived** from the formal definitions of constituents.
-
-## Dependency vocabulary
-
-- **Consumers** — constituents that mention this one in their definitions.
-- **Suppliers** — constituents this one mentions in its definition.
-- **Dependents** — direct and transitive consumers.
-- **Influencers** — direct and transitive suppliers.
-- **Generating expression** — a definition referencing a single external constituent with no added content.
-- **Base concept (for generation)** — the constituent on which a generating expression is built.
-- **Generated concept** — a constituent produced from a generating expression.
+# Доменная справка
+
+Термины, используемые в Concept Portal.
+
+## Основные термины
+
+- **Предметная область** — область, для которой строится система определений.
+- **Концептуальная схема (`КС`)** — система понятий, утверждений и связей между ними.
+- **Концептуальная модель (`КМ`)** — КС плюс интерпретация ее понятий на конечных данных.
+- **Операционная схема синтеза (`ОСС`)** — граф загрузок и синтезов КС.
+- **Родоструктурная экспликация (`RSLang`)** — формальный язык для понятий, отношений, операций и утверждений.
+- **Типизация / ступень** — структура значений выражения: элемент, целое, кортеж, множество, `Logic`.
+- **Граф термов** — зависимости: конституента ссылается на другую в формальном определении.
+
+## Конституенты
+
+**Конституента** — часть КС. Главное для агента: `alias`, `cstType`, `definitionFormal`, `term`, `definitionText`, `convention`. `comment` — комментарий и пояснения разработчика схемы, полезно для контекста.
+
+- `N#` — **номиноид**: словарная сущность. В родоструктурной экспликации не используется.
+- `X#` — **базисное множество**: неопределяемое понятие, формула пустая.
+- `C#` — **константное множество**: неопределяемое множество для арифметики и порядка, формула пустая.
+- `S#` — **родовая структура**: неопределяемое структурное понятие; формула задает типизацию.
+- `D#` — **терм**: определяемое понятие; формула вычисляет значение.
+- `F#` — **терм-функция**: параметризованный терм.
+- `P#` — **предикат-функция**: параметризованное логическое выражение.
+- `A#` — **аксиома**: логическое требование к модели.
+- `T#` — **высказывание**: логическое утверждение о модели.
+- `R#` — **радикал**: шаблонная ступень в параметрах.
+
+Правило: `X#`, `C#`, `S#` задаются конвенцией и интерпретацией; `D#`, `F#`, `P#`, `A#`, `T#` выводятся по формуле. Поставщики должны идти раньше потребителей.
+
+Не путай `S#` и `D#`: `S1: ℬ(X1×X1)` — интерпретируемое отношение из пар; `D1 := X1×X1` — декартово произведение.
+
+## Статусы выражений
+
+- `Unknown` — не проверено.
+- `OK` — корректно.
+- `Error` — ошибка в определении.
+- `Property` — неразмерное: доступна только проверка принадлежности.
+- `Incalculable` — невычислимо напрямую.
+
+## Статусы вычисления в модели
+
+- `NO_EVAL` — нечего вычислять.
+- `NOT_PROCESSED` — вычисление не запускалось.
+- `INVALID_DATA` — неверная интерпретация.
+- `EVAL_FAIL` — ошибка вычисления.
+- `AXIOM_FALSE` — аксиома ложна.
+- `EMPTY` — результат пуст.
+- `HAS_DATA` — результат вычислен и непустой.
+
+## Зависимости
+
+- **Поставщики** — конституенты, на которые ссылается текущая.
+- **Потребители** — конституенты, которые ссылаются на текущую.
+- **Влияющие** — прямые и транзитивные поставщики.
+- **Зависимые** — прямые и транзитивные потребители.
+- **Основание** — конституента, из которой формально порождают новые термы.
+- **Порожденная конституента** — построена из основания без новой предметной договоренности.
+
+## ОСС и синтез
+
+- **Загрузка** добавляет внешнюю или собственную КС в ОСС.
+- **Синтез** строит новую КС из операций-аргументов через таблицу отождествлений.
+- **Наследованные конституенты** пришли из исходных схем; их определения обычно read-only.
+- **Сквозные изменения** идут от исходной конституенты к наследникам.
+- **Ромбовидный синтез** использует КС с общими предками; чаще требует ручного отождествления дублей.
+- **Концептуальный блок** — группа схем внутри предметной области.

package/docs/GRAMMAR-REF.md

@@ -1,98 +1,47 @@
-# Grammar reference (pointers)
+# Грамматика: короткая карта
 
-Below is a compact token map agents can use without opening the grammar. For full grammar see `@rsconcept/domain` package.
+Этого обычно достаточно агенту. Полная грамматика живет в `@rsconcept/domain`.
 
-## Token classes
+## Токены
 
-| Class           | Tokens / examples                                          |
-| --------------- | ---------------------------------------------------------- |
-| Whitespace      | space, tab, newline                                        |
-| Integer literal | `0`, `42`                                                  |
-| Empty set       | `∅`                                                        |
-| Integer set     | `Z`                                                        |
-| Globals         | `X#`, `C#`, `S#`, `D#`, `F#`, `P#`, `A#`, `T#`, `N#`, `R#` |
-| Locals          | `x`, `ξ`, `μ2`, `y1`                                       |
-| Punctuation     | `(`, `)`, `[`, `]`, `{`, `}`, `,`, `;`                     |
-| Comment         | none — RSLang has no comments inside formal expressions    |
+- Литералы: `0`, `42`, `Z`, `∅`.
+- Алиасы: `X#`, `C#`, `S#`, `D#`, `F#`, `P#`, `A#`, `T#`, `R#`.
+- Локальные переменные: `x`, `ξ`, `μ2`, `y1`.
+- Скобки и разделители: `()`, `[]`, `{}`, `,`, `;`.
+- Комментариев в формальных выражениях нет.
 
-## Set / structural operators
+## Операторы
 
-| Token                | Symbol                     |
-| -------------------- | -------------------------- |
-| Union                | `∪`                        |
-| Intersection         | `∩`                        |
-| Difference           | `\`                        |
-| Symmetric difference | `∆`                        |
-| Cartesian product    | `×`                        |
-| Boolean              | `ℬ`                        |
-| Sum set              | `red`                      |
-| Singleton            | `bool`                     |
-| Desingleton          | `debool`                   |
-| Small projection     | `pr1`, `pr1,3`, …          |
-| Large projection     | `Pr1`, `Pr2,4`, …          |
-| Filter               | `Fi1[D](S)`, `Fi1,2[D](S)` |
-| Cardinality          | `card`                     |
+- Множества: `∪`, `∩`, `\`, `∆`, `×`, `ℬ`.
+- Структуры: `red`, `bool`, `debool`, `pr1`, `Pr1`, `Fi1[D](S)`, `card`.
+- Предикаты: `∈`, `∉`, `⊆`, `⊂`, `⊄`, `=`, `≠`, `<`, `≤`, `>`, `≥`.
+- Связки: `¬`, `&`, `∨`, `⇒`, `⇔`.
+- Кванторы: `∀`, `∃`.
 
-## Predicates
+Мультииндексы парсятся как список натуральных чисел: `pr1,3`, `Pr2,4`, `Fi1,2[D](S)`.
 
-| Token            | Symbol |
-| ---------------- | ------ |
-| Membership       | `∈`    |
-| Non-membership   | `∉`    |
-| Inclusion        | `⊆`    |
-| Strict inclusion | `⊂`    |
-| Non-inclusion    | `⊄`    |
-| Equality         | `=`    |
-| Inequality       | `≠`    |
-| Less             | `<`    |
-| Less-or-equal    | `≤`    |
-| Greater          | `>`    |
-| Greater-or-equal | `≥`    |
+## Декларации
 
-## Logical connectives
+- Терм-функция: `F# ::= [<params>] <body STE>`.
+- Предикат-функция: `P# ::= [<params>] <body LE>`.
+- Параметр: `α ∈ <STE>`.
+- Вызов: `F#[<arg1>, <arg2>]`.
 
-| Token       | Symbol |
-| ----------- | ------ |
-| Negation    | `¬`    |
-| Conjunction | `&`    |
-| Disjunction | `∨`    |
-| Implication | `⇒`    |
-| Equivalence | `⇔`    |
+## Приоритеты
 
-## Quantifiers
+1. Вызовы функций, проекции, `ℬ`, `bool`, `debool`, `red`, `card`.
+2. `×`.
+3. `*`.
+4. `+`, `-`.
+5. `∪`, `∩`, `\`, `∆`.
+6. Предикаты: `∈`, `=`, `<`, ...
+7. `¬`.
+8. `&`.
+9. `∨`.
+10. `⇒`.
+11. `⇔`.
 
-| Token       | Symbol |
-| ----------- | ------ |
-| Universal   | `∀`    |
-| Existential | `∃`    |
+## Когда читать исходники
 
-## Declarators
-
-| Token                 | Form                                              |
-| --------------------- | ------------------------------------------------- |
-| Function declaration  | `F# ::= [<params>] <body STE>`                    |
-| Predicate declaration | `P# ::= [<params>] <body LE>`                     |
-| Parameter declaration | `α ∈ <STE>` (commas separate; commas inside `[]`) |
-| Function call         | `F#[<arg1>, <arg2>, …]`                           |
-
-## Precedence (from highest to lowest)
-
-1. Function calls, projections, boolean
-2. Cartesian product `×`
-3. Multiplicative `*`
-4. Additive `+`, `-`
-5. Set operators `∪`, `∩`, `\`, `∆`
-6. Predicates (`∈`, `=`, `<`, …)
-7. Negation `¬`
-8. Conjunction `&`
-9. Disjunction `∨`
-10. Implication `⇒`
-11. Equivalence `⇔`
-
-Multi-index tokens inside projections / filters are parsed as a comma-separated list of natural numbers.
-
-## When to consult the full grammar
-
-- Grammar conflicts or surprising error positions — read `rslang.grammar` directly.
-- Adding new operators or precedence rules — must be done in the domain package, not in rstool.
-- Lezer terms / token IDs — see `@rsconcept/domain/src/rslang/parser/token.ts` and `parser.terms.ts`.
+- Позиция ошибки неожиданная.
+- Нужны Lezer terms/token IDs: `@rsconcept/domain/src/rslang/parser/token.ts`, `parser.terms.ts`.

package/docs/MODEL-TESTING.md

@@ -0,0 +1,57 @@
+# Тестирование определений через концептуальную модель
+
+Концептуальная модель (`КМ`) полезна как маленький стенд для проверки семантики выражений. Если агент не уверен, что формула означает именно нужную операцию, не угадывай по виду выражения: создай минимальную схему, задай тестовые значения для неопределяемых конституент и вычисли результат.
+
+## Когда использовать
+
+- Неочевидны `S#` против `D#`, проекции `Pr*` / `pr*`, фильтры `Fi*`, `red`, `bool`, `debool`.
+- Формула синтаксически корректна, но есть сомнение в семантике результата.
+- Нужно проверить, что аксиома действительно ловит ошибочные данные.
+- Пользователь просит надежно изменить важное определение, а пример данных можно сделать маленьким.
+
+Для простой проверки типизации сначала используй `analyzeExpression`. КМ нужна, когда вопрос зависит от интерпретации данных и вычисленного значения.
+
+## Минимальный цикл
+
+1. Создай отдельную `createSession` или изолированную копию текущей сессии.
+2. Добавь только нужные поставщики: `X#`, `C#`, `S#` и проверяемые `D#` / `F#` / `P#` / `A#`.
+3. Проверь формулы через `analyzeExpression` и `addOrUpdateConstituenta`.
+4. Задай значения базисов и структур через `setConstituentaValue` или `setConstituentaValues`.
+5. Вычисли проверяемую формулу через `evaluateExpression` или сохраненную конституенту через `evaluateConstituenta`.
+6. Сравни результат с ожидаемым значением; если есть несколько зависимых определений, запусти `recalculateModel`.
+
+## Что задавать руками
+
+`basic`, `constant`, `structure` можно интерпретировать напрямую. `term`, `function`, `predicate`, `axiom`, `statement` должны вычисляться из формулы, поэтому их напрямую не задавай.
+
+Пример формы данных:
+
+```ts
+const TUPLE_ID = -111;
+
+tool.setConstituentaValues(sessionId, {
+  items: [
+    { target: 1, value: { 0: 'ann', 1: 'bob', 2: 'cat' } },
+    { target: 2, value: [[TUPLE_ID, 0, 1], [TUPLE_ID, 0, 2]] }
+  ]
+});
+```
+
+Здесь `X1` получает подписи элементов, а `S1: ℬ(X1×X1)` получает множество пар по индексам элементов `X1`.
+
+## Скрипты-тесты
+
+Если проверка влияет на поведение схемы или есть риск регрессии, вынеси ее в маленький скрипт или colocated `*.test.ts`:
+
+1. Собери минимальную сессию с нужными конституентами.
+2. Задай тестовые значения неопределяемых конституент.
+3. Вычисли целевые конституенты.
+4. Проверь `success`, `status`, `diagnostics.length` и само `value`.
+
+Тест должен проверять смысл формулы, а не только отсутствие диагностик. Для аксиом отдельно проверяй положительный и отрицательный набор данных: корректная модель должна давать истинную аксиому, ошибочная — `AXIOM_FALSE` или диагностируемый сбой вычисления.
+
+## Ограничения
+
+- Маленькая КМ проверяет семантику на выбранных данных, но не доказывает определение для всех моделей.
+- Не подменяй предметное соглашение тестом: если смысл `S#` не ясен, уточни `convention` или спроси пользователя.
+- Не добавляй искусственные конституенты в рабочую схему только ради теста. Держи scratch-сессию или тестовый скрипт отдельно.