@rsconcept/rstool 1.2.2 → 1.4.0

package/docs/DOMAIN.md

@@ -20,23 +20,29 @@
 - **Тело КС** — остальные конституенты схемы, не входящие в ядро.
 - **Конвенция** — текстовое соглашение о том, как неопределяемое понятие соотносится с сущностями предметной области. В данных схемы хранится в поле `convention` конституенты. Конвенция не заменяет формальное определение и не проходит формальную проверку RSLang. Она фиксирует предметный смысл, который нельзя вывести из формулы: что именно считается элементом множества, как читать компоненты кортежа, какой порядок в паре отношения, какие константы или операции подразумеваются. В конвенции используется предметный язык и термины, которые могут быть не выражены в концептуальной схеме.
 - **Интерпретация** — соотнесение понятий КС с сущностями предметной области. В концептуальной модели задаётся значениями неопределяемых конституент и вычислением производных.
+- **Биективная переносимость** — независимость значения формального определения от биективной замены интерпретаций неопределяемых понятий. Для `X#` опирается на несравнимость элементов; анализатор RSLang отсекает формулы, нарушающие переносимость.
 
 ## Конституенты
 
-**Конституента** — часть КС. Главное для агента: `alias`, `cstType`, `definitionFormal`, `term`, `definitionText`, `convention`. `comment` — комментарий и пояснения разработчика схемы, полезно для контекста.
+**Конституента** — часть КС. Поля и правила валидации см. в [CONSTITUENTA.md](CONSTITUENTA.md); здесь только предметные роли.
 
-- `N#` — **номиноид**: словарная сущность. В родоструктурной экспликации не используется.
-- `X#` — **базисное множество**: неопределяемое понятие, формула пустая.
-- `C#` — **константное множество**: неопределяемое понятие для арифметики и порядка, формула пустая.
-- `S#` — **родовая структура**: неопределяемое структурное понятие; формула задает типизацию.
-- `D#` — **терм**: определяемое понятие; формула вычисляет значение.
-- `F#` — **терм-функция**: параметризованный терм.
-- `P#` — **предикат-функция**: параметризованное логическое выражение.
-- `A#` — **аксиома**: логическое требование к модели.
-- `T#` — **высказывание**: логическое утверждение о модели.
-- `R#` — **радикал**: шаблонная ступень в **доменах параметров** терм-функции (`F#`) или предикат-функции (`P#`). Это не конституента: в схеме нет записи с `alias` `R1`, `R2`, … и добавлять её через правку схемы не нужно. Ступень `R#` выводится в **месте вызова** `F#[…]` / `P#[…]` по типизации аргументов.
+| Обозначение | Роль                                                                                    |
+| :---------- | :-------------------------------------------------------------------------------------- |
+| `N#`        | **Номиноид**: словарная сущность вне родоструктурной экспликации                        |
+| `X#`        | **Базисное множество**: неопределяемые предметные объекты без порядка и арифметики      |
+| `C#`        | **Константное множество**: неопределяемый конечный домен с порядком и арифметикой языка |
+| `S#`        | **Родовая структура**: неопределяемое структурное понятие; формула задаёт типизацию     |
+| `D#`        | **Терм**: производное понятие, вычисляемое по формуле                                   |
+| `F#`        | **Терм-функция**: параметризованный терм                                                |
+| `P#`        | **Предикат-функция**: параметризованное логическое выражение                            |
+| `A#`        | **Аксиома**: логическое требование к модели                                             |
+| `T#`        | **Высказывание**: логическое утверждение о модели                                       |
 
-Правило: `X#`, `C#`, `S#` задаются конвенцией и интерпретацией; `D#`, `F#`, `P#`, `A#`, `T#` выводятся по формуле. Поставщики должны идти раньше потребителей. Радикалы `R#` к конституентам не относятся.
+`Z` — встроенная ступень целых в RSLang, **не конституента**. Для выбора между `X#`, `C#` и `Z` — [BASE-SELECTION.md](BASE-SELECTION.md).
+
+`R#` — **радикал**, шаблонная ступень в доменах параметров `F#` / `P#`. Это тоже **не конституента**: в схеме нет записи с `alias` `R1`, `R2`, … и добавлять её не нужно ([SYNTAX.md](SYNTAX.md), раздел «Радикалы»).
+
+Правило: `X#`, `C#`, `S#` задаются конвенцией и интерпретацией; `D#`, `F#`, `P#`, `A#`, `T#` выводятся по формуле. Поставщики должны идти раньше потребителей.
 
 Не путай `S#` и `D#`: `S1: ℬ(X1×X1)` — интерпретируемое отношение из пар; `D1 := X1×X1` — декартово произведение.
 
@@ -62,15 +68,15 @@
 
 В ответах пользователю и в конвенциях КС используй только термины из этого файла. Не вводи собственные ярлыки («базис», «базисный слой», «каркас схемы») — они не закреплены в Portal и размывают различия ниже.
 
-| Не используй                                            | Используй                                                                                   | Почему                                                   |
-| :------------------------------------------------------ | :------------------------------------------------------------------------------------------ | :------------------------------------------------------- |
-| «базис», «базисный слой», «первый слой» (без уточнения) | **неопределяемые понятия** — `X#`, `C#`, `S#`                                               | Общий термин для всего неопределяемого слоя              |
-| «базис» / «базисное» про `C#` или `S#`                  | **константное множество** (`C#`), **родовая структура** (`S#`)                              | **Базисное множество** — только про `X#`                 |
-| «базисные множества» как синоним неопределяемых понятий | **базисные множества** — только несколько `X#`; для всего слоя — **неопределяемые понятия** | `C#` и `S#` базисными множествами не называются          |
-| «ядро» = неопределяемые понятия»                        | **ядро КС** — неопределяемые понятия плюс аксиомы и производные, нужные для аксиом          | Ядро шире, чем только `X#` / `C#` / `S#`                 |
-| теорема про `T#`                                        | **высказывание** — производное логическое выражение `T#`                                    | тип теорема на Portal отсутствует и вводит в заблуждение |
-| «пропущенная конституента `R1`» в списке схемы          | **радикал** `R#` — параметр шаблона в домене `F#` / `P#`                                  | `R#` не объявляется; при ревью КС отсутствие `R1` среди конституент — норма |
-| «добавить `R1` как базисное / структурное понятие»      | оставить `R#` только в `[…]` у параметризованных `F#` / `P#`                                | иначе смешиваются шаблон и предметная КС |
+| Не используй                                            | Используй                                                                                   | Почему                                                                      |
+| :------------------------------------------------------ | :------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------- |
+| «базис», «базисный слой», «первый слой» (без уточнения) | **неопределяемые понятия** — `X#`, `C#`, `S#`                                               | Общий термин для всего неопределяемого слоя                                 |
+| «базис» / «базисное» про `C#` или `S#`                  | **константное множество** (`C#`), **родовая структура** (`S#`)                              | **Базисное множество** — только про `X#`                                    |
+| «базисные множества» как синоним неопределяемых понятий | **базисные множества** — только несколько `X#`; для всего слоя — **неопределяемые понятия** | `C#` и `S#` базисными множествами не называются                             |
+| «ядро» = неопределяемые понятия»                        | **ядро КС** — неопределяемые понятия плюс аксиомы и производные, нужные для аксиом          | Ядро шире, чем только `X#` / `C#` / `S#`                                    |
+| теорема про `T#`                                        | **высказывание** — производное логическое выражение `T#`                                    | тип теорема на Portal отсутствует и вводит в заблуждение                    |
+| «пропущенная конституента `R1`» в списке схемы          | **радикал** `R#` — параметр шаблона в домене `F#` / `P#`                                    | `R#` не объявляется; при ревью КС отсутствие `R1` среди конституент — норма |
+| «добавить `R1` как базисное / структурное понятие»      | оставить `R#` только в `[…]` у параметризованных `F#` / `P#`                                | иначе смешиваются шаблон и предметная КС                                    |
 
 ## Статусы выражений
 

package/docs/README.md

@@ -9,6 +9,7 @@
 - **DOMAIN.md** — термины Portal: конституента, неопределяемые и производные понятия, ядро/тело КС, интерпретация, ОСС, синтез.
 - **CONCEPTUAL-SCHEMA.md** — проектирование и ревью концептуальных схем.
 - **CONSTITUENTA.md** — структура и правила конституент.
+- **BASE-SELECTION.md** — выбор основания: `X#`, `C#` или `Z`.
 - **SYNTAX.md** — синтаксис RSLang: операторы, генераторы `D{}`/`I{}`/`R{}`, кванторы, `F#`/`P#`.
 - **TYPIFICATION.md** — типизация (`AnalysisResult.type`, `valueClass`).
 - **MODEL-TESTING.md** — проверка семантики определений на маленьких концептуальных моделях.

package/docs/SYNTAX.md

@@ -8,7 +8,8 @@
 - Радикалы: `R1`, `R2` — шаблонные ступени **только в доменах параметров** `[…]` у `F#` / `P#`; не конституенты и не путать с префиксом рекурсии `R{…}`.
 - Локальные переменные: `x`, `ξ`, `μ2`, `y1`.
 - Целые: `0`, `42`; отрицательного литерала нет, пиши `0 - 5`.
-- `Z` — множество целых, `∅` — пустое множество с типизацией `ℬ(R0)`.
+- `Z` — встроенная ступень целых (не конституента; отдельной записи `C#` для «целых» не нужно). Сравнение с `C#` — [BASE-SELECTION.md](BASE-SELECTION.md).
+- `∅` — пустое множество с типизацией `ℬ(R0)`.
 - Скобки и разделители: `()`, `[]`, `{}`, `,`, `;`, `|`.
 - Комментариев в формальных выражениях нет.
 
@@ -161,7 +162,7 @@ F2 ::= [α1∈R1×R2, α2∈R1] α2 = pr1(α1)
 ## Корректность
 
 - Анализ идет в глобальном контексте: все алиасы **конституент** (`X#`, `C#`, `S#`, `D#`, `F#`, `P#`, …) должны быть известны и типизированы. `R#` в доменах параметров — радикалы, не конституенты (см. выше).
-- Формальные определения должны быть биективно переносимыми (гарантируется семантическим анализатором).
+- Формальные определения должны быть **биективно переносимыми** (гарантируется семантическим анализатором): значение не зависит от переименования элементов неопределяемых понятий при согласованной замене интерпретаций. Для `X#` это запрещает порядок и арифметику над элементами; подробно — [BASE-SELECTION.md](BASE-SELECTION.md).
 - Логическая непротиворечивость проверяется примером интерпретации в модели.
 
 ## Приоритеты операторов

package/docs/TYPIFICATION.md

@@ -6,8 +6,8 @@
 
 Выражение типизировано, если его значения принадлежат ступени `H`.
 
-- `Xi`, `Ci` — элемент базисного или константного множества.
-- `Z` — целое число.
+- `Xi`, `Ci` — элемент базисного или константного множества (`Ci` — с арифметикой и порядком).
+- `Z` — целое число (встроенная ступень, не конституента). См. [BASE-SELECTION.md](BASE-SELECTION.md).
 - `(H1 × H2 × ... × Hn)` — кортеж.
 - `ℬ(H)` — множество значений ступени `H`.
 
@@ -20,13 +20,7 @@
 
 ## Радикалы
 
-`R1`, `R2`, ... — шаблонные ступени в доменах параметров `F#` / `P#`. **Не конституенты:** в КС нет и не требуется записи с `alias` `R#`.
-
-- Значение `R#` выводится по аргументам в месте вызова `F#[…]` / `P#[…]`.
-- Все вхождения одного `R#` в одном определении должны дать одну ступень.
-- Разные `R#` независимы.
-- Радикалы можно писать только в доменах параметров (в `[…]`); в теле результата будет `radicalUsage`.
-- При ревью схемы отсутствие `R1` среди конституент при наличии `R1` в формулах `F#` / `P#` — ожидаемое состояние, а не пробел ядра КС.
+`R1`, `R2`, ... — шаблонные ступени в доменах параметров `F#` / `P#`; **не конституенты**. Ступень `R#` выводится по аргументам в месте вызова; все вхождения одного `R#` в определении дают одну ступень, разные `R#` независимы. Правила и примеры — [SYNTAX.md](SYNTAX.md), раздел «Радикалы».
 
 ## `AnalysisResult.type`
 

package/examples/README.md

@@ -24,6 +24,8 @@ npx tsx node_modules/@rsconcept/rstool/examples/agent-client.ts
 
 Готовые `*-session.json` — снимки `exportSession` для `importData` и тестов. Пересобрать: соответствующий `build-*.ts` перезапишет файл рядом с собой.
 
+Перед экспортом каждый `build-*.ts` вызывает [`diagnostics-utils.ts`](diagnostics-utils.ts) (`assertCleanDiagnostics`): expression + schema + model должны быть пусты, иначе скрипт падает. Проверить все снимки: `pnpm run example:audit-diagnostics` ([`audit-diagnostics.ts`](audit-diagnostics.ts)).
+
 ## Темы и npm-скрипты
 
 - **[`sample/`](sample/):**

package/examples/agent-client.ts

@@ -14,7 +14,10 @@ async function runExample() {
     console.log('Session created:', session);
 
     await client.call('applySchemaPatch', {
-      items: [{ alias: 'X1' }, { alias: 'D1', definitionFormal: '1+2' }]
+      items: [
+        { alias: 'X1', term: 'element', convention: 'people' },
+        { alias: 'D1', definitionFormal: '1+2' }
+      ]
     });
 
     await client.call('setModelValues', {
@@ -33,8 +36,17 @@ async function runExample() {
     const analysis = await client.call<{ diagnostics: unknown[] }>('analyzeExpression', analyzeInput);
     console.log('Scratch analysis diagnostics:', analysis.diagnostics.length);
 
-    const sessionDiagnostics = await client.call<unknown[]>('listDiagnostics', {});
-    console.log('Session diagnostics count:', sessionDiagnostics.length);
+    const sessionDiagnostics = await client.call<Array<{ kind: string }>>('listDiagnostics', {});
+    const counts = { expression: 0, schema: 0, model: 0 };
+    for (const record of sessionDiagnostics) {
+      if (record.kind in counts) {
+        counts[record.kind as keyof typeof counts] += 1;
+      }
+    }
+    console.log('Session diagnostics:', {
+      total: sessionDiagnostics.length,
+      ...counts
+    });
   } finally {
     await client.close();
   }

package/examples/audit-diagnostics.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { RSToolAgent } from '../src';
+
+const sessions = [
+  'examples/sample/rsform-session.json',
+  'examples/sample/rsmodel-session.json',
+  'examples/kinship/rsform-session.json',
+  'examples/kinship/rsmodel-session.json',
+  'examples/chocolate-nim/rsform-session.json',
+  'examples/chocolate-nim/rsmodel-session.json',
+  'examples/movd/rsform-session.json',
+  'examples/movd/rsmodel-session.json',
+  'examples/expression-bank/rsform-session.json',
+  'examples/template-apply/rsform-session.json'
+];
+
+let total = 0;
+for (const rel of sessions) {
+  const path = resolve(process.cwd(), rel);
+  const tool = new RSToolAgent();
+  const payload = JSON.parse(readFileSync(path, 'utf8')) as {
+    state: { items: Array<{ id: number; alias: string }> };
+  };
+  tool.importData(payload, 'session');
+  const diags = tool.listDiagnostics();
+  total += diags.length;
+  console.log(`\n=== ${rel} (${diags.length}) ===`);
+  for (const d of diags) {
+    const alias =
+      d.alias ??
+      (d.constituentId !== undefined
+        ? (payload.state.items.find(item => item.id === d.constituentId)?.alias ?? '?')
+        : '(scratch)');
+    console.log(`  [${d.kind}] ${alias} ${d.name} ${JSON.stringify(d.params ?? [])}`);
+  }
+}
+console.log(`\nTotal: ${total}`);
+process.exit(total > 0 ? 1 : 0);

package/examples/chocolate-nim/build-rsform.ts

@@ -6,6 +6,8 @@ import { CstType, RSToolWrapperClient, type AgentConstituentaPatch } from '../..
 type DraftBatch = { draft: AgentConstituentaPatch };
 
 import { DEFAULT_RSFORM_SESSION_PATH } from './constants';
+import { CHOCOLATE_MODEL_SET } from './model-demo';
+import { assertCleanDiagnostics } from '../diagnostics-utils';
 
 /**
  * Учебная RSForm «шоколадный Ним» (ОШК-НИМ) по Portal rsforms/825.
@@ -294,6 +296,19 @@ async function run() {
       throw new Error(`${failedAlias}: analysis failed`);
     }
 
+    await client.call('setModelValues', {
+      sessionId: session.sessionId,
+      set: [...CHOCOLATE_MODEL_SET]
+    });
+    await client.call('recalculateModel', { sessionId: session.sessionId });
+
+    await assertCleanDiagnostics(
+      client,
+      session.sessionId,
+      new Map(drafts.map(entry => [entry.draft.id!, entry.draft.alias])),
+      'chocolate-nim RSForm'
+    );
+
     await client.call('commitStep', {
       sessionId: session.sessionId,
       message: 'КС «шоколадный Ним» (rsforms/825): Z×Z, pr, P#, T#, арифметика, радикал R1'

package/examples/chocolate-nim/build-rsmodel.ts

@@ -1,26 +1,11 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
-import { TUPLE_ID } from '@rsconcept/domain';
-
 import { EvalStatus, RSToolWrapperClient } from '../../src';
 
-import {
-  A1_ID,
-  D6_ID,
-  DEFAULT_RSFORM_SESSION_PATH,
-  DEFAULT_RSMODEL_SESSION_PATH,
-  S1_ID,
-  S2_ID,
-  T1_ID
-} from './constants';
-
-/**
- * Демо-позиция: шоколадка 4×6, отравленная долька в (2, 3).
- * Кучки Ним: 1, 2, 2, 3 камня; игра не окончена.
- */
-const S1_VALUE = [TUPLE_ID, 4, 6] as const;
-const S2_VALUE = [TUPLE_ID, 2, 3] as const;
+import { A1_ID, D6_ID, DEFAULT_RSFORM_SESSION_PATH, DEFAULT_RSMODEL_SESSION_PATH, T1_ID } from './constants';
+import { CHOCOLATE_MODEL_SET } from './model-demo';
+import { assertCleanDiagnostics } from '../diagnostics-utils';
 
 async function run() {
   const client = new RSToolWrapperClient({
@@ -38,10 +23,7 @@ async function run() {
 
     await client.call('setModelValues', {
       sessionId: imported.sessionId,
-      set: [
-        { target: S1_ID, value: S1_VALUE },
-        { target: S2_ID, value: S2_VALUE }
-      ]
+      set: [...CHOCOLATE_MODEL_SET]
     });
 
     const recalculated = await client.call<{
@@ -76,6 +58,17 @@ async function run() {
       throw new Error(`Expected D6=4 piles; got ${JSON.stringify(d6)}`);
     }
 
+    const state = await client.call<{ items: Array<{ id: number; alias: string }> }>('getSessionState', {
+      sessionId: imported.sessionId,
+      detail: 'full'
+    });
+    await assertCleanDiagnostics(
+      client,
+      imported.sessionId,
+      new Map(state.items.map(item => [item.id, item.alias])),
+      'chocolate-nim RSModel'
+    );
+
     await client.call('commitStep', {
       sessionId: imported.sessionId,
       message: 'Модель шоколадного Нима: 4×6, долька (2,3), четыре кучки, A1 выполняется'

package/examples/chocolate-nim/model-demo.ts

@@ -0,0 +1,11 @@
+import { TUPLE_ID } from '@rsconcept/domain';
+
+import { S1_ID, S2_ID } from './constants';
+
+export const CHOCOLATE_S1_VALUE = [TUPLE_ID, 4, 6] as const;
+export const CHOCOLATE_S2_VALUE = [TUPLE_ID, 2, 3] as const;
+
+export const CHOCOLATE_MODEL_SET = [
+  { target: S1_ID, value: CHOCOLATE_S1_VALUE },
+  { target: S2_ID, value: CHOCOLATE_S2_VALUE }
+] as const;