@rsconcept/rstool 0.10.3 → 1.0.0

package/examples/template-apply/rsform-session.json

@@ -1,43 +1,26 @@
 {
-  "contractVersion": "1.4.0",
+  "contractVersion": "2.0.0",
   "state": {
-    "sessionId": "04678669-0343-4a1c-8238-3f0de2fc12f7",
+    "sessionId": "b72f75c0-4f17-4bef-9ff3-913ea16191db",
     "alias": "",
     "title": "",
     "comment": "",
-    "createdAt": "2026-06-22T11:29:09.607Z",
-    "updatedAt": "2026-06-22T11:29:09.628Z",
+    "createdAt": "2026-07-01T17:12:54.696Z",
+    "updatedAt": "2026-07-01T17:12:54.714Z",
     "revisions": [
       {
-        "revisionId": "b577a24d-20ff-4056-992e-7662cb2e56cf",
-        "at": "2026-06-22T11:29:09.628Z",
+        "revisionId": "e85ad551-0aa0-42d9-b55d-01719aed6533",
+        "at": "2026-07-01T17:12:54.714Z",
         "message": "Применение шаблонов БВ: сотрудники, проекты, F6/F9/F20/P5"
       }
     ],
     "items": [
       {
-        "id": 1,
-        "alias": "T1",
-        "cstType": "statement",
-        "definitionFormal": "1=1",
-        "term": "Применение шаблонов банка выражений",
-        "convention": "Подстановка радикалов БВ: R1→X1, R2→X2. Отношение σ→S1 или S2. Примеры: БВ F6→F_IMAGE, БВ F20→F_SOURCES, БВ P5→P_FUNCTION",
-        "definitionText": "",
-        "analysis": {
-          "success": true,
-          "type": {
-            "typeID": 6
-          },
-          "valueClass": "value",
-          "diagnostics": []
-        }
-      },
-      {
-        "id": 2,
-        "alias": "X1",
+        "id": 3,
+        "alias": "X2",
         "cstType": "basic",
         "definitionFormal": "",
-        "term": "сотрудники",
+        "term": "проекты",
         "definitionText": "",
         "convention": "",
         "analysis": {
@@ -46,7 +29,7 @@
             "typeID": 5,
             "base": {
               "typeID": 3,
-              "baseID": "X1"
+              "baseID": "X2"
             }
           },
           "valueClass": "value",
@@ -54,11 +37,11 @@
         }
       },
       {
-        "id": 3,
-        "alias": "X2",
+        "id": 2,
+        "alias": "X1",
         "cstType": "basic",
         "definitionFormal": "",
-        "term": "проекты",
+        "term": "сотрудники",
         "definitionText": "",
         "convention": "",
         "analysis": {
@@ -67,7 +50,7 @@
             "typeID": 5,
             "base": {
               "typeID": 3,
-              "baseID": "X2"
+              "baseID": "X1"
             }
           },
           "valueClass": "value",
@@ -80,8 +63,8 @@
         "cstType": "structure",
         "definitionFormal": "ℬ(X1×X2)",
         "term": "назначение на проект",
-        "convention": "σ в шаблонах БВ для бинарных отношений двух множеств",
         "definitionText": "",
+        "convention": "σ в шаблонах БВ для бинарных отношений двух множеств",
         "analysis": {
           "success": true,
           "type": {
@@ -110,8 +93,8 @@
         "cstType": "structure",
         "definitionFormal": "ℬ(X1×X1)",
         "term": "подчинённость",
-        "convention": "σ в шаблонах БВ для бинарных отношений на одном множестве",
         "definitionText": "",
+        "convention": "σ в шаблонах БВ для бинарных отношений на одном множестве",
         "analysis": {
           "success": true,
           "type": {
@@ -134,14 +117,35 @@
           "diagnostics": []
         }
       },
+      {
+        "id": 10,
+        "alias": "D2",
+        "cstType": "term",
+        "definitionFormal": "Pr1(S2) \\ Pr2(S2)",
+        "term": "глава иерархии",
+        "definitionText": "",
+        "convention": "БВ F20: применение к S2 (развёрнуто в D2, т.к. вызов F# в терме не анализируется)",
+        "analysis": {
+          "success": true,
+          "type": {
+            "typeID": 5,
+            "base": {
+              "typeID": 3,
+              "baseID": "X1"
+            }
+          },
+          "valueClass": "value",
+          "diagnostics": []
+        }
+      },
       {
         "id": 6,
         "alias": "F_IMAGE",
         "cstType": "function",
         "definitionFormal": "[α∈X1, σ∈ℬ(X1×X2)] Pr2(Fi1[{α}](σ))",
         "term": "проекты сотрудника",
-        "convention": "БВ F6: R1→X1, R2→X2",
         "definitionText": "",
+        "convention": "БВ F6: R1→X1, R2→X2",
         "analysis": {
           "success": true,
           "type": {
@@ -192,8 +196,8 @@
         "cstType": "function",
         "definitionFormal": "[σ∈ℬ(X1×X1)] Pr1(σ) \\ Pr2(σ)",
         "term": "вершины без предшественников",
-        "convention": "БВ F20 (истоки графа подчинённости)",
         "definitionText": "",
+        "convention": "БВ F20 (истоки графа подчинённости)",
         "analysis": {
           "success": true,
           "type": {
@@ -237,8 +241,8 @@
         "cstType": "predicate",
         "definitionFormal": "[α∈ℬ(X1), σ∈ℬ(X1×X2)] card(Pr1(σ)) = card(σ) & Pr1(σ) = α",
         "term": "тотальная функция X1→X2",
-        "convention": "БВ P5",
         "definitionText": "",
+        "convention": "БВ P5",
         "analysis": {
           "success": true,
           "type": {
@@ -288,8 +292,8 @@
         "cstType": "term",
         "definitionFormal": "Pr2(Fi1[X1](S1))",
         "term": "все назначенные проекты",
-        "convention": "БВ F9: образ множества X1 по S1",
         "definitionText": "",
+        "convention": "БВ F9: образ множества X1 по S1",
         "analysis": {
           "success": true,
           "type": {
@@ -304,21 +308,17 @@
         }
       },
       {
-        "id": 10,
-        "alias": "D2",
-        "cstType": "term",
-        "definitionFormal": "Pr1(S2) \\ Pr2(S2)",
-        "term": "глава иерархии",
-        "convention": "БВ F20: применение к S2 (развёрнуто в D2, т.к. вызов F# в терме не анализируется)",
+        "id": 1,
+        "alias": "T1",
+        "cstType": "statement",
+        "definitionFormal": "1=1",
+        "term": "Применение шаблонов банка выражений",
         "definitionText": "",
+        "convention": "Подстановка радикалов БВ: R1→X1, R2→X2. Отношение σ→S1 или S2. Примеры: БВ F6→F_IMAGE, БВ F20→F_SOURCES, БВ P5→P_FUNCTION",
         "analysis": {
           "success": true,
           "type": {
-            "typeID": 5,
-            "base": {
-              "typeID": 3,
-              "baseID": "X1"
-            }
+            "typeID": 6
           },
           "valueClass": "value",
           "diagnostics": []

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rsconcept/rstool",
-  "version": "0.10.3",
-  "description": "Agent-facing library for incremental RSForm construction, RSLang analysis, diagnostics, modeling, and evaluation. Wraps @rsconcept/domain with a deterministic session contract and stdio wrapper.",
+  "version": "1.0.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",
   "repository": {

package/skills/rstool-helper/EXAMPLES.md

@@ -1,161 +1,89 @@
-# Примеры rstool
+# RSLang и rstool — примеры (контракт 2.0)
 
-Короткие примеры для агентов. Полные скрипты и JSON-сессии — `../../examples/` ([README](../../examples/README.md)). Воркфлоу — [GUIDE.md](GUIDE.md).
-
-## Минимальная сессия
+## Схема: batch patch
 
 ```ts
 import { CstType, RSToolAgent } from '@rsconcept/rstool';
 
 const tool = new RSToolAgent();
-const { sessionId } = tool.createSession();
-
-tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
-});
 
-tool.addOrUpdateConstituenta(sessionId, {
-  draft: {
-    id: 2,
-    alias: 'S1',
-    cstType: CstType.STRUCTURED,
-    definitionFormal: 'ℬ(X1×X1)',
-    convention: 'Множество пар: родитель и его ребёнок из людей. Порядок в паре задаётся конвенцией.'
-  }
+const result = tool.applySchemaPatch({
+  initial: { title: 'Example' },
+  commitMessage: 'initial',
+  items: [{ alias: 'X1' }, { alias: 'S1', definitionFormal: 'ℬ(X1×X1)' }, { alias: 'D1', definitionFormal: 'Pr1(S1)' }]
 });
 
-const { state, diagnostics } = tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
-});
-
-console.log(state.analysis.success, diagnostics.length);
+console.log(result.summary.itemCount, result.success);
 ```
 
-## Анализ перед upsert
-
-Черновой анализ, когда синтаксис или `cstType` под вопросом.
+## Анализ без сохранения
 
 ```ts
-const analysis = tool.analyzeExpression(sessionId, {
+const analysis = tool.analyzeExpression({
   expression: 'Pr1(S1)',
   cstType: CstType.TERM
 });
-
-if (!analysis.success) {
-  console.log(analysis.diagnostics.map(({ code, from, to }) => ({ code, from, to })));
-}
 ```
 
-Исправь диапазон `from` / `to` из отчёта и повтори анализ. При необходимости пересмотри определение целиком или разбей на несколько конституент.
-
-## Вычисление
+## Состояние сессии
 
 ```ts
-tool.setConstituentaValue(sessionId, {
-  target: 1,
-  value: { 0: 'zero', 1: 'one' }
-});
-
-const scratch = tool.evaluateExpression(sessionId, {
-  expression: '1+2',
-  cstType: CstType.TERM
-});
-
-console.log(scratch.success, scratch.value); // true, 3
+const summary = tool.getSessionState(); // compact
+const full = tool.getSessionState('full'); // SessionState clone
+const diags = tool.listDiagnostics();
 ```
 
-Для сохранённых определений задай значения `basic`, `constant` и `structure`, затем вызови `evaluateConstituenta` или `recalculateModel`.
-
-## Семантический smoke-тест
-
-Синтаксис верен, но смысл неочевиден — собери маленькую модель и проверь значение.
+## Модель и вычисление
 
 ```ts
-import { TUPLE_ID } from '@rsconcept/domain';
-import { CstType, EvalStatus, RSToolAgent } from '@rsconcept/rstool';
+await tool.setModelValues({
+  set: [{ target: 1, value: { '0': 'alice', '1': 'bob' } }]
+});
 
-const tool = new RSToolAgent();
-const { sessionId } = tool.createSession();
+const evalResult = tool.evaluate({ constituentId: 2 });
+const scratch = tool.evaluate({ expression: '1+2', cstType: CstType.TERM });
+const recalc = tool.recalculateModel();
+```
 
-tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
-});
-tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 2, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' }
-});
-tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
-});
+## Экспорт / импорт
 
-tool.setConstituentaValues(sessionId, {
-  items: [
-    { target: 1, value: { 0: 'ann', 1: 'bob', 2: 'cat' } },
-    {
-      target: 2,
-      value: [
-        [TUPLE_ID, 0, 1],
-        [TUPLE_ID, 0, 2]
-      ]
-    }
-  ]
-});
+```ts
+const payload = tool.exportSession();
+const restored = tool.importData(payload, 'session');
 
-const result = tool.evaluateConstituenta(sessionId, { constituentId: 3 });
+const schemaJson = tool.exportPortal({ kind: 'schema' });
+const modelObj = tool.exportPortal({ kind: 'model', format: 'object' });
 
-if (!result.success || result.status !== EvalStatus.HAS_DATA || JSON.stringify(result.value) !== '[0]') {
-  throw new Error(`Ожидалось Pr1(S1) = первая координата; получено ${JSON.stringify(result)}`);
-}
+// Portal GET /api/rsforms/:id/details
+const session = tool.importData(portalDetailsJsonString);
 ```
 
-Подробнее: `../../docs/MODEL-TESTING.md`.
+## Stdio (плоские params)
 
-## Клиент обёртки
+```json
+{ "id": "1", "method": "applySchemaPatch", "params": { "items": [{ "alias": "X1" }] } }
+{ "id": "2", "method": "setModelValues", "params": { "set": [{ "target": 1, "value": { "0": "a" } }] } }
+{ "id": "3", "method": "evaluate", "params": { "constituentId": 2 } }
+```
 
-Когда агент общается с отдельным процессом `rstool-wrapper`.
+## Node-клиент
 
 ```ts
-import { CstType } from '@rsconcept/rstool';
 import { RSToolWrapperClient } from '@rsconcept/rstool/wrapper';
 
+// Из checkout rstool: по умолчанию запускает `npm run wrapper` в текущем cwd.
+// Для установленного пакета: new RSToolWrapperClient({ command: 'npx', args: ['rstool-wrapper'] }).
 const client = new RSToolWrapperClient();
 await client.waitUntilReady();
 
-const { sessionId } = await client.call<{ sessionId: string }>('createSession');
-
-await client.call('addOrUpdateConstituenta', {
-  sessionId,
-  input: {
-    draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
-  }
+await client.call('applySchemaPatch', {
+  items: [{ alias: 'X1' }, { alias: 'D1', definitionFormal: '1+2' }]
 });
 
-const diagnostics = await client.call('listDiagnostics', { sessionId });
-console.log(diagnostics);
+await client.call('setModelValues', {
+  set: [{ target: 1, value: { 0: 'zero', 1: 'one' } }]
+});
 
+const evalResult = await client.call('evaluate', { constituentId: 2 });
 await client.close();
 ```
-
-Ручной stdio — один JSON-запрос на строку:
-
-```jsonl
-{ "id": "1", "method": "createSession", "params": {} }
-{ "id": "2", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 1, "alias": "X1", "cstType": "basic", "definitionFormal": "" } } } }
-```
-
-## Экспорт / импорт
-
-```ts
-const payload = tool.exportSession(sessionId);
-const restored = tool.importSession(payload);
-```
-
-Экспорт включает состояние сессии и значения модели.
-
-Файлы для загрузки пользователем в существующий объект Portal:
-
-```ts
-const schemaJson = tool.exportPortalSchema(sessionId);
-const modelJson = tool.exportPortalModel(sessionId);
-```
-
-`schemaJson` — на странице схемы, `modelJson` — на странице модели, через **Load from JSON**.

package/skills/rstool-helper/GUIDE.md

@@ -4,18 +4,27 @@
 
 **RSLang** — формальная нотация концептуальных схем: понятия, отношения, операции, утверждения. Основа: принадлежность `x∈y`, теоретико-множественные и логические выражения, типизация.
 
-**rstool** — API агента для сессий, upsert, анализа, диагностик, значений модели, вычисления, экспорта/импорта.
+**rstool** — API агента для сессий, редактирования схемы, анализа, диагностик, значений модели, вычисления, экспорта/импорта.
 
 - Библиотека: `@rsconcept/rstool`.
 - Анализатор: `@rsconcept/domain`.
 - Stdio-обёртка: `npx rstool-wrapper`, JSON построчно.
 - Node-клиент: `RSToolWrapperClient`.
 
+## Быстрый контракт для агента
+
+- Library API: `tool.applySchemaPatch(input, sessionId?)` — единственный путь правки схемы.
+- Stdio/MCP: **плоские** `params` — поля метода и optional `sessionId` на одном уровне (без `params.input`).
+- Состояние: `getSessionState()` (summary) или `getSessionState('full')`.
+- Импорт/экспорт Portal: `importData`, `exportPortal({ kind })`.
+- Модель: `setModelValues`, `evaluate`, `recalculateModel`.
+- Перед сохранением сомнительной формулы — `analyzeExpression`.
+
 ## Что читать
 
 Пути — относительно этого файла.
 
-- API, методы, stdio, коды ошибок: [REFERENCE.md](REFERENCE.md).
+- API, методы, stdio: [REFERENCE.md](REFERENCE.md).
 - Примеры: [EXAMPLES.md](EXAMPLES.md).
 - Термины предметной области: [../../docs/DOMAIN.md](../../docs/DOMAIN.md).
 - Концептуализация, создание схемы: [../../docs/CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md).
@@ -36,16 +45,16 @@
 
 Когда схема уже есть и нужны точечные правки, новые конституенты или проверка формул.
 
-1. `createSession` (или продолжить существующую сессию).
-2. Развивай схему — добавляй конституенты с корректным `cstType` и атрибутами.
-3. Добавляй поставщиков раньше потребителей (см. [порядок объявления](#порядок-объявления-конституент)).
-4. Перед upsert при сомнении вызывай `analyzeExpression`.
+1. Продолжи текущую сессию или вызови `ensureSession`; большинство методов создают сессию лениво.
+2. Развивай схему через `applySchemaPatch`: можно опускать `id` и `cstType` для стандартных alias `X/C/S/D/A/F/P`.
+3. Для пачки конституент передавай все элементы вместе — `applySchemaPatch` упорядочит поставщиков раньше потребителей.
+4. Перед patch в `applySchemaPatch` при сомнении вызывай `analyzeExpression`.
 5. Исправляй диагностики по диапазону `from` / `to` в `definitionFormal` ([DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md)).
 6. При сомнении в семантике собери маленькую КМ и проверь тестовые данные ([цикл КМ](#проверка-на-маленькой-км)).
-7. Задай базовые/модельные значения: `setConstituentaValue(s)`; вычисли: `evaluateExpression`, `evaluateConstituenta`, `recalculateModel`.
-8. `commitStep`, когда состояние согласовано.
-9. Сохрани: `exportSession` / `importSession`.
-10. Для загрузки в Portal: `exportPortalSchema` (схема) или `exportPortalModel` (модель).
+7. Задай значения модели: `setModelValues`; вычисли: `evaluate`, `recalculateModel`.
+8. `commitStep` или `commitMessage` в `applySchemaPatch`, когда состояние согласовано.
+9. Сохрани: `exportSession` / `importData`.
+10. Для загрузки в Portal: `exportPortal({ kind: 'schema' })` или `{ kind: 'model' }`.
 
 ### Оценка или правка КС из Portal
 
@@ -56,13 +65,8 @@
 Если id неизвестен — контекстный поиск `GET /api/library/context-search?q=...`, затем
 метаданные по найденным id: `GET /api/library/by-ids?ids=...` (curl и поля поиска — в том же файле).
 
-Portal JSON из `/details` не является форматом `exportSession` и не передаётся в
-`importSession` напрямую. Создай `createSession({ title, alias, comment: description })`
-и перенеси `items[]` через `addOrUpdateConstituenta`, сохраняя raw-поля:
-`cst_type → cstType`, `definition_formal → definitionFormal`,
-`term_raw → term`, `definition_raw → definitionText`, `convention → convention`.
-После переноса запусти `listDiagnostics`; для результата в Portal используй
-`exportPortalSchema`, а для локального снапшота — `exportSession`.
+Portal JSON из `/details` не является форматом `exportSession`. Используй `importData(payload)` —
+auto определит `portal-details` или `portal-schema`. Явный kind: `'portal-details'`, `'portal-schema'`, `'session'`.
 
 ### Концептуализация (КС из содержания источника)
 
@@ -75,7 +79,7 @@ Portal JSON из `/details` не является форматом `exportSessio
 5. Добавь `A#` на структуры: `card`, покрытие `Pr1,2(S#)=…`, принадлежность выбора.
 6. Введи `F#` для типовых запросов.
 7. Производные понятия строй через `Pr*`, `Fi*`, `F#` от центрального `D#` и базовых `S#`.
-8. Перед каждым upsert — `analyzeExpression`; при ошибках — [цикл диагностик](#цикл-диагностик).
+8. Перед каждым patch — `analyzeExpression`; при ошибках — [цикл диагностик](#цикл-диагностик).
 9. Сомнительную семантику проверь на маленькой КМ ([цикл КМ](#проверка-на-маленькой-км), [MODEL-TESTING.md](../../docs/MODEL-TESTING.md)).
 10. Перед показом результата пройди [чеклист ревью КС](#ревью-концептуальной-схемы).
 
@@ -90,7 +94,7 @@ Portal JSON из `/details` не является форматом `exportSessio
 3. Сопоставь `code` с исправлением в [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
 4. Исправь именно диапазон в `definitionFormal`.
 5. Не повторяй вызов без изменения ввода.
-6. После успеха — `addOrUpdateConstituenta`.
+6. После успеха — ещё один `applySchemaPatch` с исправленным элементом.
 
 ### Проверка на маленькой КМ
 
@@ -98,9 +102,9 @@ Portal JSON из `/details` не является форматом `exportSessio
 
 1. Отдельная `createSession` или изолированная копия текущей сессии.
 2. Только нужные поставщики: `X#`, `C#`, `S#` и проверяемые `D#` / `F#` / `P#` / `A#`.
-3. `analyzeExpression` и `addOrUpdateConstituenta`.
-4. Значения базовых понятий: `setConstituentaValue` / `setConstituentaValues`.
-5. `evaluateExpression` или `evaluateConstituenta`; сравни с ожидаемым `value`.
+3. `analyzeExpression` и `applySchemaPatch`.
+4. Значения: `setModelValues`.
+5. `evaluate`; сравни с ожидаемым `value`.
 6. При нескольких зависимых определениях — `recalculateModel`.
 
 Для регрессий вынеси проверку в скрипт или colocated `*.test.ts` (см. [MODEL-TESTING.md](../../docs/MODEL-TESTING.md)).
@@ -114,13 +118,24 @@ Portal JSON из `/details` не является форматом `exportSessio
 
 Правила валидации по типам — [CONSTITUENTA.md](../../docs/CONSTITUENTA.md).
 
+## Формат ответа агента
+
+В конце работы сообщи:
+
+- что изменено в схеме или модели;
+- есть ли активные диагностики;
+- какой экспорт получен: session / Portal schema / Portal model;
+- какие проверки выполнены: analyze / evaluate / recalculate / tests.
+
+Не вставляй большой JSON в чат без запроса пользователя.
+
 ## Чеклисты
 
 ### Сессия и rstool
 
-- [ ] Отслеживается `sessionId`.
-- [ ] `cstType` соответствует роли конституенты.
-- [ ] Поставщики добавлены раньше потребителей.
+- [ ] Используется текущая сессия (`getSessionState`) или явный `sessionId`, если сессий несколько.
+- [ ] Для стандартных alias `X/C/S/D/A/F/P` можно доверить `cstType` `applySchemaPatch`; нестандартные alias передаются с явным `cstType`.
+- [ ] Для пачки конституент предпочитай один `applySchemaPatch` с массивом `items`.
 
 ### Перед показом, commit и export