@rsconcept/rstool 1.7.0 → 1.9.0

package/docs/MODEL-TESTING.md

@@ -35,6 +35,16 @@ await tool.setModelValues({
 
 Здесь `X1` получает подписи элементов, а `S1: ℬ(X1×X1)` получает множество пар по индексам элементов `X1`.
 
+- Порядок элементов и дубликаты во входе не важны: `setModelValues` приводит значения `S#` к канонической форме (сортировка `compare`, без повторов). В `getModelState` и в результатах вычисления множества всегда отсортированы — сравнивай с ожиданием как с отсортированным массивом.
+- Кортежи — `[TUPLE_ID, …]`; вложенные множества — обычные массивы (`ℬℬ(X1)`: `[[0, 1], [2]]`).
+- `status` в `evaluate` / `recalculateModel` — числовой `EvalStatus` (`7` `HAS_DATA`, `6` `EMPTY`, `5` `AXIOM_FALSE`, `4` `EVAL_FAIL`); таблица — в `REFERENCE.md`.
+
+## Чтение результата
+
+- Конституента: `evaluate({ constituentId })` — вычисляет её и все поставщики.
+- Scratch: `evaluate({ expression, cstType })`. `cstType` задаёт ожидаемую ступень: `'term'` — множество или число, `'axiom'` — логическое выражение (`P1[S1]`, `D2⊆S1`). В scratch-выражении можно ссылаться на любые конституенты схемы, включая производные `D#`.
+- Литералов элементов `X#` в ЯРЭ нет: выражай тестовые элементы через схему (`debool(D3)`, `Pr1(S1)\Pr2(S1)`), а не через подписи.
+
 ## Скрипты-тесты
 
 Если проверка влияет на поведение схемы или есть риск регрессии, вынеси ее в маленький скрипт или colocated `*.test.ts`:
@@ -46,6 +56,44 @@ await tool.setModelValues({
 
 Тест должен проверять смысл формулы, а не только отсутствие диагностик. Для аксиом отдельно проверяй положительный и отрицательный набор данных: корректная модель должна давать истинную аксиому, ошибочная — `AXIOM_FALSE` или диагностируемый сбой вычисления.
 
+```ts
+import { EvalStatus, TUPLE_ID } from '@rsconcept/domain';
+
+// X1 — вершины, S1: ℬ(X1×X1) — рёбра, A1 ::= ∀α∈X1 α∉F4[α] — ацикличность
+const X1 = 1,
+  S1 = 2,
+  A1 = 17;
+await tool.setModelValues({
+  set: [
+    { target: X1, value: { 0: 'a', 1: 'b', 2: 'c' } },
+    {
+      target: S1,
+      value: [
+        [TUPLE_ID, 0, 1],
+        [TUPLE_ID, 1, 2]
+      ]
+    }
+  ]
+});
+let a1 = tool.evaluate({ constituentId: A1 });
+// a1.status === EvalStatus.HAS_DATA, a1.value === 1
+
+await tool.setModelValues({
+  set: [
+    {
+      target: S1,
+      value: [
+        [TUPLE_ID, 0, 1],
+        [TUPLE_ID, 1, 2],
+        [TUPLE_ID, 2, 0]
+      ]
+    }
+  ]
+});
+a1 = tool.evaluate({ constituentId: A1 });
+// a1.status === EvalStatus.AXIOM_FALSE, a1.value === 0
+```
+
 ## Ограничения
 
 - Маленькая КМ проверяет семантику на выбранных данных, но не доказывает определение для всех моделей.

package/docs/README.md

@@ -11,6 +11,7 @@
 - **CONSTITUENTA.md** — структура и правила конституент.
 - **BASE-SELECTION.md** — выбор основания: `X#`, `C#` или `Z`.
 - **SYNTAX.md** — синтаксис ЯРЭ: операторы, генераторы `D{}`/`I{}`/`R{}`, кванторы, `F#`/`P#`.
+- **CONSTRUCTIONS.md** — объяснение формул и конструкций человеку (карточки, разбор снаружи внутрь).
 - **TYPIFICATION.md** — типизация (`AnalysisResult.type`, `valueClass`).
 - **MODEL-TESTING.md** — проверка семантики определений на маленьких концептуальных моделях.
 - **DIAGNOSTICS.md** — диагностики анализа и способы исправления ошибок.

package/docs/SYNTAX.md

@@ -1,6 +1,6 @@
 # Синтаксис ЯРЭ
 
-Единая справка для агента: читай при построении или исправлении `definitionFormal`. Типизация — `TYPIFICATION.md`; ошибки — `DIAGNOSTICS.md`.
+Единая справка для агента: читай при построении или исправлении `definitionFormal`. Типизация — `TYPIFICATION.md`; ошибки — `DIAGNOSTICS.md`. Объяснение человеку — [CONSTRUCTIONS.md](CONSTRUCTIONS.md).
 
 ## Имена и литералы
 

package/docs/TYPIFICATION.md

@@ -25,8 +25,17 @@
 ## `AnalysisResult.type`
 
 1. Сначала проверь `analysis.success === true` и `analysis.type !== null`.
-2. Не разбирай объект вручную; используй helpers из `@rsconcept/domain`.
-3. `valueClass` уточняет вычислимость: `Value`, `Property`, `Invalid`.
+2. Не разбирай объект вручную; печатай через `labelType` из `@rsconcept/domain/rslang/labels`:
+
+   ```ts
+   import { labelType } from '@rsconcept/domain/rslang/labels';
+
+   labelType(analysis.type); // 'ℬ(X1×X1)', '[X1] → ℬ(X1)', '[ℬ(X1×X1)] → Logic', 'Logic'
+   ```
+
+   Для скрипта вне пакета — `file:///<workspace>/rsconcept/domain/src/rslang/labels.ts` (см. GUIDE, «Как запускать rstool»). `normalizeType` из того же модуля даёт каноническую строку для сравнения типизаций.
+
+3. `valueClass` уточняет вычислимость: `'value'` (вычислимо), `'property'` (только проверка принадлежности), `null` (ошибка). `success: true` не исключает диагностику `error`: квантор по `ℬ(…)` разбирается, но даёт `invalidPropertyUsage` и `valueClass: null`.
 
 ## `S#` и `D#`
 

package/examples/diagnostics-utils.ts

@@ -5,10 +5,9 @@ export type ExampleDiagnostic = Diagnostic;
 export function formatDiagnostics(diags: ExampleDiagnostic[], aliasById?: ReadonlyMap<number, string>): string {
   return diags
     .map(d => {
-      const alias =
-        d.alias ??
-        (d.constituentId !== undefined ? (aliasById?.get(d.constituentId) ?? '?') : '(scratch)');
-      return `[${d.kind}] ${alias} ${d.name} ${JSON.stringify(d.params ?? [])}`;
+      const alias = d.alias ?? (d.constituentId !== undefined ? (aliasById?.get(d.constituentId) ?? '?') : '(scratch)');
+      const stack = d.stack && d.stack.length > 0 ? ` stack=${d.stack.map(frame => frame.alias).join('←')}` : '';
+      return `[${d.kind}] ${alias} ${d.name} ${JSON.stringify(d.params ?? [])}${stack}`;
     })
     .join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsconcept/rstool",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Agent-facing library for incremental RSForm construction, RSLang analysis, diagnostics, modeling, and evaluation. Wraps @rsconcept/domain with a deterministic session contract.",
   "license": "MIT",
   "author": "IRBorisov",
@@ -50,6 +50,23 @@
     "README.md",
     "LICENSE"
   ],
+  "dependencies": {
+    "eslint": "^10.9.1",
+    "eslint-plugin-simple-import-sort": "^14.0.0",
+    "@rsconcept/domain": "3.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "@vitest/coverage-v8": "^4.1.11",
+    "tsdown": "^0.22.14",
+    "tsx": "^4.23.13",
+    "typescript": "^6.0.3",
+    "unrun": "^0.3.1",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -68,22 +85,6 @@
     "example:build-expression-bank-schema": "tsx examples/expression-bank/build-rsform.ts",
     "example:build-template-apply-schema": "tsx examples/template-apply/build-rsform.ts",
     "example:audit-diagnostics": "tsx examples/audit-diagnostics.ts",
-    "kinship:cli": "tsx examples/kinship/cli.ts",
-    "prepublishOnly": "pnpm run build"
-  },
-  "dependencies": {
-    "@rsconcept/domain": "workspace:*"
-  },
-  "devDependencies": {
-    "@types/node": "^26.1.0",
-    "@vitest/coverage-v8": "^4.1.9",
-    "tsdown": "^0.22.3",
-    "tsx": "^4.22.5",
-    "typescript": "^6.0.3",
-    "unrun": "^0.3.1",
-    "vitest": "^4.1.9"
-  },
-  "publishConfig": {
-    "access": "public"
+    "kinship:cli": "tsx examples/kinship/cli.ts"
   }
-}
+}

package/skills/README.md

@@ -9,7 +9,7 @@ Each skill lives in its own subdirectory: `skills/<skill-name>/SKILL.md` (plus r
 - `rstool-helper/GUIDE.md`: entry point — task→read matrix, workflows (incl. review), checklists (Russian)
 - `rstool-helper/REFERENCE.md`: API, stdio, MCP names, response shapes, help map (Russian)
 - `rstool-helper/EXAMPLES.md`: snippets, anti-patterns, diagnostics, `examples/` index (Russian)
-- `../docs/*.md`: language reference (DOMAIN, SYNTAX, DIAGNOSTICS, …)
+- `../docs/*.md`: language reference (DOMAIN, SYNTAX, CONSTRUCTIONS, DIAGNOSTICS, …)
 
 ## npm workflow
 

package/skills/rstool-helper/EXAMPLES.md

@@ -153,6 +153,7 @@ tool.applySchemaPatch({
 | `globalFuncParenCall`                             | `F1(ξ)`                                            | `F1[ξ]`                                                          |
 | `globalFuncWithoutArgs`                           | голое `F1` в формуле                               | `F1[…]`                                                          |
 | `radicalUsage`                                    | `R1` в теле формулы или как конституента           | `R#` только в `[…]` у `F#`/`P#`                                  |
+| `invalidPropertyUsage`                            | `∀σ∈ℬ(S1)\{∅} ¬P1[σ]` — квантор по булеану         | вычислимая форма через достижимость: `∀α∈X1 α∉F4[α]`             |
 | `schemaMissingConvention`                         | `X1` без конвенции                                 | добавь предметную конвенцию                                      |
 | `schemaHomonym`                                   | одинаковый термин у разных конституент             | различай термины                                                 |
 | `schemaDependencyCycle`                           | круг в определениях (`F3 → P1 → F3`)               | разорви цикл: убери взаимные ссылки                              |
@@ -237,6 +238,29 @@ const scratch = tool.evaluate({ expression: '1+2', cstType: CstType.TERM });
 const recalc = tool.recalculateModel();
 ```
 
+Множества `S#` — кортежи `[TUPLE_ID, i, j]` по индексам `X#`; порядок во входе не важен (нормализуется). Scratch может ссылаться на производные конституенты; логические выражения — с `cstType: CstType.AXIOM`:
+
+```ts
+import { EvalStatus, TUPLE_ID } from '@rsconcept/domain';
+
+await tool.setModelValues({
+  set: [
+    { target: 1, value: { 0: 'a', 1: 'b', 2: 'c' } },
+    {
+      target: 2,
+      value: [
+        [TUPLE_ID, 1, 2],
+        [TUPLE_ID, 0, 1]
+      ]
+    } // S1: ℬ(X1×X1)
+  ]
+});
+const closure = tool.evaluate({ constituentId: 9 }); // D9 — транзитивное замыкание
+closure.status === EvalStatus.HAS_DATA; // status — число: 7
+const check = tool.evaluate({ expression: 'S1⊆D9', cstType: CstType.AXIOM });
+check.value === 1;
+```
+
 ## Экспорт / импорт и Portal round-trip
 
 ```ts

package/skills/rstool-helper/GUIDE.md

@@ -18,7 +18,7 @@
 - Stdio/MCP: **плоские** `params` — поля метода и optional `sessionId` на одном уровне (без `params.input`).
 - Состояние: `getSessionState()` (summary) или `getSessionState('full')`.
 - Импорт/экспорт Portal: `importData`, `exportPortal({ kind })`.
-- Модель: `setModelValues`, `evaluate`, `recalculateModel`.
+- Модель: `setModelValues`, `evaluate`, `recalculateModel`. Статусы вычисления приходят числами (`EvalStatus`, см. REFERENCE).
 - Перед сохранением сомнительной формулы — `analyzeExpression`.
 
 ## Задача → чтение
@@ -31,9 +31,10 @@
 | Оценить / отревьюить готовую КС (без запроса «перепиши») | этот GUIDE → [ревью / оценка](#ревью--оценка-готовой-кс); [чеклист ревью](#ревью-концептуальной-схемы); [CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md); при импорте — [PORTAL-API.md](../../docs/PORTAL-API.md)             | EXAMPLES с batch patch; полный SYNTAX    |
 | Точечные правки существующей схемы                       | этот GUIDE → [редактирование](#редактирование-и-проверка-схемы); [REFERENCE.md](REFERENCE.md) при вызовах                                                                                                                            | CONCEPTUAL-SCHEMA целиком                |
 | Починить формулу / диагностики                           | этот GUIDE → [цикл диагностик](#цикл-диагностик); [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md); [EXAMPLES.md](EXAMPLES.md) «типичные диагностики»                                                                                     | CONCEPTUAL-SCHEMA; PORTAL-API            |
+| Написать формулу; синтаксис `D{}`/`I{}`/`R{}`, `F#`/`P#` | [SYNTAX.md](../../docs/SYNTAX.md); при необходимости [EXAMPLES.md](EXAMPLES.md)                                                                                                                                                      | CONSTRUCTIONS; воркфлоу сессий           |
+| Объяснить формулу или конструкцию человеку               | [CONSTRUCTIONS.md](../../docs/CONSTRUCTIONS.md)                                                                                                                                                                                      | SYNTAX целиком; воркфлоу сессий          |
 | Импорт / правка по ссылке Portal                         | этот GUIDE → [Portal](#оценка-или-правка-кс-из-portal); [PORTAL-API.md](../../docs/PORTAL-API.md)                                                                                                                                    | SYNTAX; BASE-SELECTION                   |
 | Проверить смысл на данных / КМ                           | этот GUIDE → [КМ](#проверка-на-маленькой-км); [MODEL-TESTING.md](../../docs/MODEL-TESTING.md)                                                                                                                                        | DOMAIN/ОСС; CONCEPTUAL-SCHEMA            |
-| Объяснить синтаксис / генераторы / `F#`/`P#`             | [SYNTAX.md](../../docs/SYNTAX.md); при необходимости [EXAMPLES.md](EXAMPLES.md)                                                                                                                                                      | воркфлоу сессий                          |
 | Разобрать типизацию / ступени                            | [TYPIFICATION.md](../../docs/TYPIFICATION.md)                                                                                                                                                                                        | PORTAL-API                               |
 | Вызовы API / stdio / MCP                                 | [REFERENCE.md](REFERENCE.md)                                                                                                                                                                                                         | docs языка                               |
 | Термины КС, ядро/тело, не путать ярлыки                  | [DOMAIN.md](../../docs/DOMAIN.md)                                                                                                                                                                                                    | —                                        |
@@ -56,10 +57,28 @@
 Из корня workspace Portal (после `pnpm install` и сборки `@rsconcept/domain`):
 
 ```bash
-pnpm --filter @rsconcept/rstool exec tsx path/to/your/build-schema.ts
+pnpm --filter @rsconcept/rstool exec tsx C:/path/to/review.mts
 ```
 
-В скрипте импортируй API пакета (`@rsconcept/rstool` или относительный путь к `rsconcept/rstool/src` только если скрипт лежит вне пакета и это осознанный выбор). Либо используй stdio/MCP без отдельного файла.
+Правила для скрипта **вне** `rsconcept/rstool/`:
+
+- `import … from '@rsconcept/rstool'` из такого файла **не резолвится** — пакет не поднят в корневой `node_modules`. Импортируй по абсолютному `file://` URL: `file:///<workspace>/rsconcept/rstool/src/index.ts` (или `…/dist/index.js`). На Windows абсолютный путь без `file://` тоже падает (`ERR_UNSUPPORTED_ESM_URL_SCHEME`).
+- Расширение **`.mts`**: `.ts` вне пакета трактуется как CommonJS, а `@rsconcept/*` экспортируют только ESM (`ERR_PACKAGE_PATH_NOT_EXPORTED`).
+- Helpers domain — тем же способом: `file:///…/rsconcept/domain/src/index.ts` (`TUPLE_ID`), `…/domain/src/rslang/labels.ts` (`labelType`).
+- Вывод в файл с `-Encoding utf8` (PowerShell) — в консоли cp1251 символы ЯРЭ ломаются.
+
+```ts
+import { readFileSync } from 'node:fs';
+// <workspace> — абсолютный путь к корню Portal, например D:/work/Portal или /home/me/Portal
+import { RSToolAgent } from 'file:///<workspace>/rsconcept/rstool/src/index.ts';
+import { TUPLE_ID } from 'file:///<workspace>/rsconcept/domain/src/index.ts';
+
+const tool = new RSToolAgent();
+tool.importData(readFileSync('C:/tmp/details.json', 'utf-8'));
+console.log(tool.listDiagnostics());
+```
+
+Альтернатива без резолвинга — stdio-обёртка из собранного `dist`: `RSToolWrapperClient({ command: 'node', args: ['<abs>/rsconcept/rstool/dist/wrapper/stdio-wrapper.js'], cwd: '<abs>/rsconcept/rstool' })`. Внутри пакета (тесты, штатные `examples/`) обычный `@rsconcept/rstool` работает.
 
 ## Что читать
 
@@ -72,6 +91,7 @@ pnpm --filter @rsconcept/rstool exec tsx path/to/your/build-schema.ts
 - Концептуализация, создание схемы: [../../docs/CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md).
 - Конституенты и валидация: [../../docs/CONSTITUENTA.md](../../docs/CONSTITUENTA.md).
 - Синтаксис ЯРЭ: [../../docs/SYNTAX.md](../../docs/SYNTAX.md).
+- Объяснение формул и конструкций: [../../docs/CONSTRUCTIONS.md](../../docs/CONSTRUCTIONS.md).
 - Типизация: [../../docs/TYPIFICATION.md](../../docs/TYPIFICATION.md).
 - Проверка определений на КМ: [../../docs/MODEL-TESTING.md](../../docs/MODEL-TESTING.md).
 - Диагностики: [../../docs/DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
@@ -130,19 +150,20 @@ kind `auto` (default) определит `portal-details` или `portal-schema`
 **Правило:** без явного запроса на правку не делай массовый рефакторинг и не заменяй схему «улучшенной версией». Сначала отчёт; правки — только по согласованию или если пользователь сразу сказал «исправь».
 
 1. Загрузи схему: текущая сессия, `importData`, или Portal → [PORTAL-API.md](../../docs/PORTAL-API.md).
-2. `listDiagnostics()` — раздели `expression` / `schema` / `model`; зафиксируй ошибки и предупреждения.
-3. `getSessionState('summary')` — обзор состава; при необходимости `full` для формул.
+2. `listDiagnostics()` — раздели `expression` / `schema` / `model`; зафиксируй ошибки и предупреждения. `analysisSuccess: true` в summary **не** означает отсутствие диагностик (например, `invalidPropertyUsage` даёт `error` при успешном разборе) — опирайся на `listDiagnostics`.
+3. `getSessionState('summary')` — обзор состава; при необходимости `full` для формул. Типизацию из `analysis.type` печатай через `labelType` ([TYPIFICATION.md](../../docs/TYPIFICATION.md)), а не разбирай AST вручную.
 4. Структурный проход по [чеклисту ревью](#ревью-концептуальной-схемы) и [CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md):
    - неопределяемые vs производные (`S#` там, где должно быть `D#`/`F#`/`P#`);
    - `X#` / `C#` / `Z` ([BASE-SELECTION.md](../../docs/BASE-SELECTION.md));
    - терм-функции vs множества пар;
    - радикалы `R#` не объявлены конституентами;
    - покрытие задачи vs избыточность.
-5. Severity в отчёте:
-   - **блокер** — диагностики `error`, схема не анализируется / ломает вычисление;
-   - **важно** — нарушение правил проектирования (лишнее `S#`, график вместо `F#`, смешение экспликаций);
-   - **замечание** — стиль, именование, возможные упрощения, пробелы покрытия.
-6. Ответ — по [шаблону ревью](#шаблон-ответа-ревью). Предлагай конкретные правки списком; применяй их только по запросу.
+5. Severity в отчёте — по **смыслу** диагностики, а не только по полю `severity` (инструмент помечает `error` и метаданные):
+   - **блокер** — `expression` с `severity: error` (формула не разбирается, невычислима: `invalidPropertyUsage`, …), `schemaDependencyCycle`, `schemaFormalDuplicate`, `schemaHomonym`; схема не анализируется / ломает вычисление;
+   - **важно** — нарушение правил проектирования (лишнее `S#`, график вместо `F#`, смешение экспликаций, перекрёстные ссылки `C#`, термин сильнее формулы);
+   - **замечание** — `schemaMissingConvention`, `schemaMissingTerm`, `modelEmpty` у структур, не задействованных в проверке; стиль, именование, упрощения, пробелы покрытия.
+6. Проверь на маленькой КМ ключевые производные и аксиомы ([цикл КМ](#проверка-на-маленькой-км)): позитивный набор данных → ожидаемые значения, негативный → `AXIOM_FALSE`. Это чаще всего даёт главные находки (расхождение термина и формулы, лишние/пропущенные элементы).
+7. Ответ — по [шаблону ревью](#шаблон-ответа-ревью). Предлагай конкретные правки списком; применяй их только по запросу.
 
 ### Цикл диагностик
 
@@ -150,8 +171,8 @@ kind `auto` (default) определит `portal-details` или `portal-schema`
 
 1. Вызови `listDiagnostics()` — смотри `kind`: `expression` (формула), `schema` (омонимы, дубликаты, термин/конвенция), `model` (интерпретация).
 2. Для черновика формулы — `analyzeExpression` (без сохранения).
-3. Прочитай `name`, `severity`, `alias`, `from`, `to`, `params` в `analysis.diagnostics` или через `listDiagnostics({ kind })`.
-4. Сопоставь `name` (или `code`) с исправлением в [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
+3. Прочитай `name`, `severity`, `alias`, `from`, `to`, `params`, при вычислении — ещё `stack` (цепочка `F#`/`P#`, см. [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md)), в `analysis.diagnostics` или через `listDiagnostics({ kind })`.
+4. Сопоставь `name` (или `code`) с исправлением в [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md). Для runtime-ошибок внутри вызова смотри `stack[0]` — там реальный locus, а не только call site в корневом выражении.
 5. Исправь именно диапазон в `definitionFormal` (expression) или метаданные/данные модели (schema/model).
 6. Не повторяй вызов без изменения ввода.
 7. После успеха — ещё один `applySchemaPatch` / `setModelValues` с исправлением.
@@ -160,12 +181,14 @@ kind `auto` (default) определит `portal-details` или `portal-schema`
 
 Когда синтаксис верен, но смысл формулы неочевиден. Подробности и форма данных — [MODEL-TESTING.md](../../docs/MODEL-TESTING.md).
 
-1. Отдельная `createSession` или изолированная копия текущей сессии.
+1. Отдельная `createSession` или изолированная копия текущей сессии (для ревью схемы из Portal достаточно самой импортированной сессии).
 2. Только нужные поставщики: `X#`, `C#`, `S#` и проверяемые `D#` / `F#` / `P#` / `A#`.
 3. `analyzeExpression` и `applySchemaPatch`.
-4. Значения: `setModelValues`.
-5. `evaluate`; сравни с ожидаемым `value`.
-6. При нескольких зависимых определениях — `recalculateModel`.
+4. Значения: `setModelValues`. `X#` — `{ 0: 'a', 1: 'b' }` (индекс → подпись), `S#` — массив кортежей `[TUPLE_ID, i, j]` по индексам `X#`; порядок элементов не важен, значения приводятся к канонической форме автоматически.
+5. `evaluate({ constituentId })` для конституенты; `evaluate({ expression, cstType })` для scratch-выражения — `cstType` задаёт ожидаемую ступень: множества и числа — `'term'`, логические выражения (`P1[S1]`, `D2⊆S1`) — `'axiom'`. В scratch можно ссылаться на любые конституенты схемы, включая `D#` — зависимости вычисляются автоматически.
+6. `status` в ответе — **число** (`EvalStatus`): `7` `HAS_DATA`, `6` `EMPTY`, `5` `AXIOM_FALSE`, `4` `EVAL_FAIL`, `3` `INVALID_DATA`, `1` `NO_EVAL`; полный список — [REFERENCE.md](REFERENCE.md). Сравни `value` с ожидаемым.
+7. При нескольких зависимых определениях — `recalculateModel`.
+8. Для аксиом — два набора данных: корректный (истина) и нарушающий (`AXIOM_FALSE`).
 
 Для регрессий вынеси проверку в скрипт или colocated `*.test.ts` (см. [MODEL-TESTING.md](../../docs/MODEL-TESTING.md)).
 
@@ -194,8 +217,8 @@ kind `auto` (default) определит `portal-details` или `portal-schema`
 2. **Диагностики:** число ошибок / предупреждений по `expression` / `schema` / `model` (без полного JSON).
 3. **Находки** списком: блокер → важно → замечание; у каждой — имя конституенты и суть.
 4. **Покрытие:** что из задачи отражено; чего не хватает.
-5. **Рекомендации:** конкретные правки; не применяй их без запроса.
-6. **Проверки:** что уже сделано (import, listDiagnostics, выборочный анализ).
+5. **Рекомендации:** конкретные правки; не применяй их без запроса. Предложенную замену формулы прогони через анализ выражения (и по возможности через КМ) до того, как её советовать.
+6. **Проверки:** что уже сделано (импорт, диагностики, выборочный анализ) и **КМ**: данные → ожидание → результат для проверенных конституент.
 
 ### Шаблон ответа: диагностики
 
@@ -206,10 +229,14 @@ kind `auto` (default) определит `portal-details` или `portal-schema`
 
 ### Шаблон ответа: объяснение формулы
 
+Полный сценарий и карточки конструкций — [CONSTRUCTIONS.md](../../docs/CONSTRUCTIONS.md). Кратко:
+
 - роль конституенты и термин;
 - формула как есть;
-- по шагам: что вычисляется / утверждается;
-- на какие понятия опирается; типизация.
+- ТМВ или ЛВ;
+- снаружи внутрь, только конструкции из формулы;
+- ступень и опоры;
+- вычисление на данных — только по запросу.
 
 ### Язык ответа
 
@@ -252,7 +279,7 @@ kind `auto` (default) определит `portal-details` или `portal-schema`
 - [ ] Схема проверена; ошибки исправлены.
 - [ ] Диагностики обработаны до фиксации шага и экспорта.
 - [ ] В тексте ответа нет английских имён полей и методов API — использованы термины из раздела [Язык ответа](#язык-ответа).
-- [ ] Нет неофициальных ярлыков («базис», «базисный слой») — термины КС из [DOMAIN.md](../../docs/DOMAIN.md).
+- [ ] Нет неофициальных ярлыков («базис», «базисы», «базисный слой», «базовые понятия») — термины КС из [DOMAIN.md](../../docs/DOMAIN.md), раздел **«Термины: не путать»**. Для `X#` говори **базисное множество**, не «базис».
 
 ### Ревью концептуальной схемы
 

package/skills/rstool-helper/REFERENCE.md

@@ -5,7 +5,7 @@
 ## Контракт rstool
 
 - Пакет: `@rsconcept/rstool`
-- Версия контракта: `3.2.0` (`CONTRACT_VERSION`)
+- Версия контракта: `3.3.0` (`CONTRACT_VERSION`)
 - Основной класс: `RSToolAgent`
 - Публичные импорты: `@rsconcept/rstool` и `@rsconcept/rstool/wrapper`
 - Опции: `new RSToolAgent({ persistenceDir? })` — каталог для сохранения сессий между перезапусками (stdio/MCP: `RSTOOL_PERSISTENCE_DIR`)
@@ -114,9 +114,11 @@ tool.listDiagnostics({ kind: 'expression' });
 tool.listDiagnostics({ kind: 'schema', constituentId: 3, severity: 'error' });
 ```
 
-Фильтры: `kind?: 'expression' | 'schema' | 'model'`, `constituentId?`, `severity?: 'error' | 'warning'`.
+Фильтры: `kind?: 'expression' | 'schema' | 'model'`, `constituentId?`, `severity?: 'error' | 'warning'`. В stdio / MCP те же поля передаются **плоско** в `params` (`{ "kind": "schema", "severity": "warning" }`); stdio дополнительно принимает устаревший вложенный `filters`.
 
-Элемент диагностики (агентский вид): `kind`, `code`, `name`, `severity`, `alias?`, `expression`, `from`, `to`, `params?`. Ключ для поиска исправления — `name` ([DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md)).
+`severity` отражает правило инструмента, а не вес для ревью: `schemaMissingConvention` / `schemaMissingTerm` приходят как `error`. Как ранжировать в отчёте — [GUIDE.md](GUIDE.md), «Ревью / оценка готовой КС».
+
+Элемент диагностики (агентский вид): `kind`, `code`, `name`, `severity`, `alias?`, `expression`, `from`, `to`, `params?`, `stack?` (цепочка вызовов при ошибке внутри `F#`/`P#`). Ключ для поиска исправления — `name` ([DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md)).
 
 ## `analyzeExpression`
 
@@ -132,6 +134,8 @@ tool.analyzeExpression({
 
 **Результат:** `{ success, type, valueClass, diagnostics }`. Не сохраняет конституенту. Для черновика формулы — до `applySchemaPatch`.
 
+`type` — AST типизации; для чтения используй `labelType` из `@rsconcept/domain/rslang/labels` (`ℬ(X1×X1)`, `[X1] → ℬ(X1)`, `Logic`). `success: true` совместим с диагностикой `error` (например, `invalidPropertyUsage` при `valueClass: null`) — проверяй `diagnostics`.
+
 ## `evaluate`
 
 Ровно один вариант входа:
@@ -141,7 +145,19 @@ tool.analyzeExpression({
 
 **Результат:** `{ success, value, status, iterations, cacheHits, diagnostics }`.
 
-`status` — статус вычисления КМ (`HAS_DATA`, `EMPTY`, `AXIOM_FALSE`, `EVAL_FAIL`, … — [DOMAIN.md](../../docs/DOMAIN.md)).
+`status` — статус вычисления КМ, **числовой** код `EvalStatus` (`@rsconcept/domain`); смысл — [DOMAIN.md](../../docs/DOMAIN.md):
+
+| Код | Имя             | Смысл                                   |
+| --: | --------------- | --------------------------------------- |
+| `1` | `NO_EVAL`       | не вычисляется (`X#`, `C#`, `F#`, `P#`) |
+| `2` | `NOT_PROCESSED` | вычисление не запускалось               |
+| `3` | `INVALID_DATA`  | неверная интерпретация                  |
+| `4` | `EVAL_FAIL`     | ошибка вычисления                       |
+| `5` | `AXIOM_FALSE`   | аксиома ложна                           |
+| `6` | `EMPTY`         | результат пуст                          |
+| `7` | `HAS_DATA`      | вычислено, непусто                      |
+
+Scratch-выражение: `cstType` задаёт ожидаемую ступень (`term` — множество / число, `axiom` — логическое). Ссылки на `D#` / `A#` / `T#` внутри scratch допустимы — их значения (и зависимости через `F#` / `P#`) вычисляются перед оценкой.
 
 ## `setModelValues` / `getModelState` / `recalculateModel`
 
@@ -155,8 +171,9 @@ await tool.setModelValues({
 - `set[]`: `{ target, value, type? }` — `target` = id конституенты; `type` обычно не нужен.
 - `clear[]`: id для сброса значений.
 - Метод **async**. После изменения данных пересчитываются диагностики модели.
+- Значения `S#` приводятся к канонической форме (сортировка, без дубликатов) — порядок элементов во входе не важен; в `getModelState` хранится уже нормализованное значение.
 - `getModelState()` → `{ items: [{ id, type, value }] }`.
-- `recalculateModel()` → `{ items: [{ id, alias, value, status }] }`.
+- `recalculateModel()` → `{ items: [{ id, alias, value, status }] }` (`status` — числовой `EvalStatus`, таблица выше).
 
 Формы `value` для `X#` / `S#` — [MODEL-TESTING.md](../../docs/MODEL-TESTING.md).
 
@@ -237,6 +254,7 @@ JSON-строка сессии для последующего `importData(...,
 {"id":"9","method":"exportPortal","params":{"kind":"schema"}}
 {"id":"10","method":"importData","params":{"payload":"..."}}
 {"id":"11","method":"getSessionState","params":{"detail":"summary"}}
+{"id":"12","method":"listDiagnostics","params":{"kind":"expression","severity":"error"}}
 ```
 
 ## Help map: ошибка → документ
@@ -245,6 +263,7 @@ JSON-строка сессии для последующего `importData(...,
 | -------------------------------------------------- | ------------------------------------------------------- |
 | Код / `name` диагностики                           | [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md)             |
 | Синтаксис операторов, `D{}`/`I{}`/`R{}`, `F#`/`P#` | [SYNTAX.md](../../docs/SYNTAX.md)                       |
+| Объяснить формулу / конструкцию человеку           | [CONSTRUCTIONS.md](../../docs/CONSTRUCTIONS.md)         |
 | Ступени, `AnalysisResult.type`                     | [TYPIFICATION.md](../../docs/TYPIFICATION.md)           |
 | `X#` vs `C#` vs `Z`, переносимость                 | [BASE-SELECTION.md](../../docs/BASE-SELECTION.md)       |
 | Проектирование, `F#` vs пары, ревью                | [CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md) |

package/skills/rstool-helper/SKILL.md

@@ -2,8 +2,9 @@
 name: rstool-helper
 description: >-
   ЯРЭ и концептуальные схемы через rstool: концептуализация, ревью/оценка КС,
-  правки и диагностики формул, проверка на КМ (evaluate), выбор X#/C#/Z,
-  импорт/экспорт Portal (/rsforms, /details). Читай GUIDE и docs из node_modules.
+  правки и диагностики формул, объяснение конструкций ЯРЭ, проверка на КМ (evaluate),
+  выбор X#/C#/Z, импорт/экспорт Portal (/rsforms, /details).
+  Читай GUIDE и docs из node_modules.
 ---
 
 # rstool-helper
@@ -39,9 +40,11 @@ description: >-
 | Собрать / развить КС из текста    | GUIDE: концептуализация; `docs/CONCEPTUAL-SCHEMA.md`; `docs/BASE-SELECTION.md` |
 | Оценить / отревьюить готовую КС   | GUIDE: ревью; чеклист ревью; `docs/CONCEPTUAL-SCHEMA.md`                       |
 | Починить формулу / диагностики    | GUIDE: цикл диагностик; `docs/DIAGNOSTICS.md`                                  |
+| Написать формулу / синтаксис      | `docs/SYNTAX.md`                                                               |
+| Объяснить формулу / конструкцию   | `docs/CONSTRUCTIONS.md`                                                        |
 | Импорт / правка по ссылке Portal  | GUIDE: Portal; `docs/PORTAL-API.md`                                            |
 | Проверить смысл на данных         | GUIDE: КМ; `docs/MODEL-TESTING.md`                                             |
-| Синтаксис / типизация / вызов API | `docs/SYNTAX.md` / `TYPIFICATION.md` / `REFERENCE.md`                          |
+| Типизация / вызов API             | `docs/TYPIFICATION.md` / `REFERENCE.md`                                        |
 
 Перед работой всегда открой **GUIDE.md**; остальное — по строке таблицы.
 
@@ -51,7 +54,7 @@ description: >-
 
 ## Язык ответа пользователю
 
-В тексте для пользователя используй термины предметной области («формальное определение», «конституента», «диагностики»), а не английские имена полей и методов API (`definitionFormal`, `applySchemaPatch`). Идентификаторы API — только в коде, patch-ах и JSON. Словарь API → текст: раздел «Язык ответа» в GUIDE.md. Термины КС (базовые понятия, базисное множество, ядро) — только из `docs/DOMAIN.md`, раздел **«Термины: не путать»**.
+В тексте для пользователя используй термины предметной области («формальное определение», «конституента», «диагностики»), а не английские имена полей и методов API (`definitionFormal`, `applySchemaPatch`). Идентификаторы API — только в коде, patch-ах и JSON. Словарь API → текст: раздел «Язык ответа» в GUIDE.md. Термины КС (**неопределяемые понятия**, **базисное множество**, ядро) — только из `docs/DOMAIN.md`, раздел **«Термины: не путать»**. Не сокращай «базисное множество» до «базис» / «базисы».
 
 ## Portal (приложение)
 

package/src/mappers/diagnostic-assembly.ts

@@ -6,7 +6,7 @@ import {
 } from '@rsconcept/domain/library';
 import { type DiagnosticSourceFields } from '@rsconcept/domain/library/rsform-api';
 import { EvalStatus } from '@rsconcept/domain/library/rsmodel';
-import { isCritical, RSErrorCode, type RSErrorDescription } from '@rsconcept/domain/rslang/error';
+import { isCritical, RSErrorCode, type EvalStackFrame, type RSErrorDescription } from '@rsconcept/domain/rslang/error';
 
 export { DiagnosticKind, RSDiagnosticCode };
 
@@ -22,6 +22,8 @@ export interface Diagnostic extends CstDiagnostic {
   expression: string;
   from: number;
   to: number;
+  /** Evaluation call chain when the fault is inside a called `F#`/`P#` body. */
+  stack?: readonly EvalStackFrame[];
 }
 
 /** Context for attributing a {@link Diagnostic} to a constituent. */
@@ -72,7 +74,8 @@ export function expressionDiagnostic(
     expression,
     from: error.from,
     to: error.to,
-    ...(error.params ? { params: error.params } : {})
+    ...(error.params ? { params: error.params } : {}),
+    ...(error.stack ? { stack: error.stack } : {})
   };
 }
 

package/src/mappers/model-adapter.ts

@@ -1,5 +1,7 @@
 import { DiagnosticKind, expressionDiagnostic } from './diagnostic-assembly';
 import { type RSErrorDescription, type Value } from '@rsconcept/domain/rslang';
+import { extractGlobals } from '@rsconcept/domain/rslang/api';
+import { normalizeValue } from '@rsconcept/domain/rslang/eval/value-api';
 import { isBaseSet } from '@rsconcept/domain/library/rsform-api';
 import { CstType, type RSForm } from '@rsconcept/domain/library/rsform';
 import { RSEngine, type RSEngineServices } from '@rsconcept/domain/library/rsengine';
@@ -37,7 +39,11 @@ export class ModelAdapter {
       const binding = toBasicBinding(input.value as Record<string | number, string>);
       await engine.setBasicValue(input.target, binding);
     } else {
-      await engine.setStructureValue(input.target, input.value as Value);
+      // Set operations in the evaluator assume canonical form (sorted, deduplicated);
+      // agents may pass elements in arbitrary order.
+      const value = structuredClone(input.value) as Value;
+      normalizeValue(value);
+      await engine.setStructureValue(input.target, value);
     }
     session.updatedAt = new Date().toISOString();
     return structuredClone(session.model);
@@ -64,6 +70,7 @@ export class ModelAdapter {
 
   public evaluateExpression(session: SessionState, expression: string, cstType: CstType): EvaluationResult {
     const engine = this.createEngine(session);
+    this.prepareReferencedValues(engine, session, expression);
     const result = engine.evaluateExpression(expression, cstType);
     const status =
       result.value === null
@@ -120,6 +127,32 @@ export class ModelAdapter {
     return engine;
   }
 
+  /**
+   * Computes values of inferrable constituents referenced by a scratch expression (directly or
+   * through `F#` / `P#` bodies). A fresh engine only holds interpreted `X#` / `C#` / `S#` values.
+   */
+  private prepareReferencedValues(engine: RSEngine, session: SessionState, expression: string): void {
+    const schema = engine.schema;
+    if (!schema) {
+      return;
+    }
+    const globals = extractGlobals(expression);
+    const referenced = session.items.filter(item => globals.has(item.alias)).map(item => item.id);
+    if (referenced.length === 0) {
+      return;
+    }
+    const required = new Set([...referenced, ...schema.graph.expandAllInputs(referenced)]);
+    for (const cstID of schema.graph.topologicalOrder()) {
+      if (!required.has(cstID)) {
+        continue;
+      }
+      const cst = schema.cstByID.get(cstID);
+      if (cst && isInferrable(cst.cst_type)) {
+        engine.calculateCst(cstID);
+      }
+    }
+  }
+
   private validateSetInput(session: SessionState, input: SetConstituentaValueInput): void {
     const cst = session.items.find(item => item.id === input.target);
     if (!cst) {

package/src/mappers/types.ts

@@ -9,6 +9,7 @@ export interface DomainErrorLike {
   from: number;
   to: number;
   params?: readonly string[];
+  stack?: RSErrorDescription['stack'];
 }
 
 /** Minimal domain analysis shape before mapping to {@link AnalysisResult}. */