@rsconcept/rstool 0.4.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +16 -17
  2. package/docs/CONCEPTUAL-SCHEMA.md +93 -44
  3. package/docs/CONSTITUENTA.md +11 -9
  4. package/docs/DOMAIN.md +9 -1
  5. package/docs/MODEL-TESTING.md +8 -2
  6. package/docs/PORTAL-API.md +1 -0
  7. package/docs/README.md +1 -1
  8. package/docs/TYPIFICATION.md +3 -9
  9. package/package.json +1 -1
  10. package/skills/rstool-helper/EXAMPLES.md +53 -64
  11. package/skills/rstool-helper/GUIDE.md +11 -37
  12. package/skills/rstool-helper/REFERENCE.md +19 -23
  13. package/skills/rstool-helper/SKILL.md +2 -4
package/README.md CHANGED
@@ -4,7 +4,7 @@ Agent-facing library for **incremental RSForm construction**, **RSLang expressio
4
4
 
5
5
  ## Agent skill
6
6
 
7
- RS language + rstool workflows for agents: `skills/rstool-helper/` (`GUIDE.md`, `REFERENCE.md`, `EXAMPLES.md`) and `docs/` (`DOMAIN.md`, `SYNTAX.md`, …). A **thin** entry skill is installed into the project’s agent skills folder; see [Installing the agent skill](#installing-the-agent-skill) below.
7
+ RS language + rstool workflows for agents: `skills/rstool-helper/` (`GUIDE.md`, `REFERENCE.md`, `EXAMPLES.md`) and `docs/` (`DOMAIN.md`, `CONCEPTUAL-SCHEMA.md`, `SYNTAX.md`, …). A **thin** entry skill is installed into the project’s agent skills folder; see [Installing the agent skill](#installing-the-agent-skill) below.
8
8
 
9
9
  ## Install
10
10
 
@@ -12,7 +12,21 @@ RS language + rstool workflows for agents: `skills/rstool-helper/` (`GUIDE.md`,
12
12
  npm install @rsconcept/rstool
13
13
  ```
14
14
 
15
- `@rsconcept/domain` is a peer-of-dependency installed automatically. No Portal checkout is required.
15
+ `@rsconcept/domain` is a peer-of-dependency installed automatically.
16
+
17
+ ## Installing the agent skill
18
+
19
+ After `npm install @rsconcept/rstool`, **you do not copy files yourself**. Ask your agent, for example:
20
+
21
+ > Install the rstool agent skill according to the package instructions.
22
+
23
+ The agent should read and follow:
24
+
25
+ `node_modules/@rsconcept/rstool/skills/INSTALL.md`
26
+
27
+ That copies `skills/rstool-helper/SKILL.md` from the package into your host’s project skills directory (for example `.agents/skills/rstool-helper/SKILL.md`). Full guidance stays in the package (`skills/rstool-helper/GUIDE.md`, `docs/*.md`) and is read from `node_modules` when needed.
28
+
29
+ Details: `skills/README.md`.
16
30
 
17
31
  ## Quick use (library)
18
32
 
@@ -50,7 +64,6 @@ await client.close();
50
64
  - Parse / syntax / semantic / type analysis for expressions.
51
65
  - In-memory modeling: set base bindings and structured values; evaluate expressions and constituents.
52
66
  - Deterministic diagnostics and export/import for reproducible agent workflows.
53
- - Library API + stdio JSON wrapper as the only supported transports (MCP adapter lives in [`@rsconcept/rstool-mcp`](../rstool-mcp/)).
54
67
 
55
68
  ## Publishing
56
69
 
@@ -128,20 +141,6 @@ The example:
128
141
  - sets a base binding and evaluates a term
129
142
  - fetches diagnostics
130
143
 
131
- ## Installing the agent skill
132
-
133
- After `npm install @rsconcept/rstool`, **you do not copy files yourself**. Ask your agent, for example:
134
-
135
- > Install the rstool agent skill according to the package instructions.
136
-
137
- The agent should read and follow:
138
-
139
- `node_modules/@rsconcept/rstool/skills/INSTALL.md`
140
-
141
- That copies `skills/rstool-helper/SKILL.md` from the package into your host’s project skills directory (for example `.agents/skills/rstool-helper/SKILL.md`). Full guidance stays in the package (`skills/rstool-helper/GUIDE.md`, `docs/*.md`) and is read from `node_modules` when needed.
142
-
143
- Details: `skills/README.md`.
144
-
145
144
  ## License
146
145
 
147
146
  MIT
package/docs/CONCEPTUAL-SCHEMA.md CHANGED
@@ -1,78 +1,127 @@
1
1
  # Концептуальная схема
2
2
 
3
- Справка про проектирование КС как системы определений. Для механики см. `CONSTITUENTA.md`, `SYNTAX.md`, `TYPIFICATION.md`.
3
+ Общие правила проектирования КС как системы определений. Механика: `CONSTITUENTA.md`, `SYNTAX.md`, `TYPIFICATION.md`.
4
4
 
5
- ## Цель схемы
5
+ ## Цель
6
6
 
7
- КС ценна не числом конституент, а различениями, которые она вводит.
7
+ КС ценна не числом конституент, а различениями.
8
8
 
9
- - Добавляй понятие, если оно дает новый критерий, роль, отношение, инвариант или правило.
10
- - Если пользователь постоянно переформулирует одно различие, введи отдельную конституенту.
9
+ - Добавляй конституенту, если есть новый критерий выбора, роль, отношение, инвариант или правило.
10
+ - Если одно различие постоянно переформулируется, выдели отдельную конституенту.
11
+ - Не копируй источник дословно. Строй предметную модель.
12
+ - Разработка КС ведется итеративно - вводи понятия, экспликцируй определения, формируй новый понтия, исследуй предметную область.
11
13
 
12
- ## Текстовые поля
14
+ ## Предметная редукция
13
15
 
14
- `term`, `definitionText`, `convention` держи в языке схемы и в ее словаре.
16
+ Концептуализация решает задачу, не переписывает весь источник.
15
17
 
16
- - `term` — короткое имя понятия.
17
- - `definitionText` — текстовая интерпретация формального определения.
18
- - `convention` — соглашение для неопределяемого понятия.
19
-
20
- Перед записью `definitionText` проверь существительные: важный предметный термин должен быть введен как `N#`, `X#`, `C#`, `S#` или `D#`.
18
+ - Рассматривай только нужный аспект определения.
19
+ - Нужно опускать неважные отношения.
20
+ - Можно не различать предметные термины, если задача не требует различения.
21
+ - Если различение влияет на критерий, вывод или проверку, введи его явно.
21
22
 
22
23
  ## Номиноиды и атрибутирование
23
24
 
24
- `N#` — номиноид: именованная сущность для словаря схемы. Он помогает фиксировать термин до точной родоструктурной формализации.
25
+ `N#` — номиноид: именованная сущность словаря до точной родоструктурной формализации.
26
+
27
+ Атрибутирование связывает `N#` с конституентами отношением "быть атрибутом". Это отдельная атрибутивная экспликация, не замена `S#`, `D#`, `A#`.
28
+
29
+ Правило: не смешивай атрибутивную и родоструктурную экспликацию без явного запроса.
25
30
 
26
- Атрибутирование связывает номиноид с другими конституентами через атрибуты. Это отдельная атрибутивная экспликация, не замена `S#`, `D#`, `A#` в родоструктурной экспликации.
31
+ ## Базовые понятия
27
32
 
28
- Правило для `rstool`: не смешивай атрибутивную и родоструктурную экспликацию. Используй `N#` как словарную опору, но не превращай атрибуты в RS-формулы и не добавляй атрибутивные связи, если пользователь явно не просит совместить эти способы.
33
+ `X#`, `C#`, и `S#` — это базовые понятия, их нельзя строить одно из другого и включать друг в друга как элементы или подмножества.
34
+ Если такое возникает — значит есть скрытое отношение, его нужно явно оформить отдельной производной конституентой.
35
+ Если базисные множества пересекаются по интерпретации или набор констант показывает какой-то атрибут — отсутствует нужное отношение, его надо ввести.
29
36
 
30
37
  ## Родовые структуры
31
38
 
32
- `S#` — родовая структура. Ее `definitionFormal` задает типизацию, а смысл задают конвенция, интерпретация и аксиомы.
39
+ `S#` — родовая структура. `definitionFormal` задает типизацию; смысл задают `convention`, интерпретация, аксиомы.
33
40
 
34
- Паттерн для отношения:
41
+ Паттерн отношения:
35
42
 
36
43
  1. `X1` — базисное множество.
37
- 2. `S1: ℬ(X1×X1)` — отношение; порядок пары описан в `convention`.
44
+ 2. `S1: ℬ(X1×X1)` — отношение; предметное пояснение в `convention`.
38
45
  3. `D# := Pr1(S1)`, `D# := Pr2(S1)` — именованные компоненты.
39
- 4. Сложные термы строятся поверх этих `D#`.
46
+ 4. Сложные термы строятся поверх этих `D#` и `S#`.
47
+
48
+ Повторяется `Pr2(Fi1[...](...))` или похожая цепочка -> введи промежуточный `D#` или `F#`.
49
+
50
+ ## Relation-first
51
+
52
+ Используй, когда нужно объединить несколько КС или в термах повторяются длинные цепочки `∃d1…∃dn`.
53
+
54
+ Строй слоями; слой ссылается только на предыдущие:
55
+
56
+ | Слой | Роль | Ввод |
57
+ | :--- | :-------------------- | :----------------------------------------------------------------------------- |
58
+ | 1 | Базисные множества | `X#`, `C#`; пустой `definitionFormal`, смысл в `convention` / `definitionText` |
59
+ | 2 | Структуры | `S#`; типизация `ℬ(…×…)`, конвенция кортежа |
60
+ | 3 | Инварианты | `A#`; короткие ограничения, чаще через `card` |
61
+ | 4 | Доступ | `F#`; локальный API вида `[α∈…] Pr*(Fi*[…](S#))` |
62
+ | 5 | Центральное отношение | один `D#` или `S#`, задающий полную траекторию синтеза |
63
+ | 6 | Витрина | `D#` через `Pr*`, `Fi*`, `card`, `red`; узкие `F#` для аналитики |
64
+
65
+ ## Центральное отношение
66
+
67
+ Единый сценарий фиксируй одним объектом:
68
+
69
+ ```text
70
+ D13 ::= I{(α, ξ1, τ, ξ2, β1, β2, ρ, ξ3) |
71
+ α∈S6; ξ1∈X2; τ∈F7[α,ξ1]; …; ξ3∈S3
72
+ }
73
+ ```
74
+
75
+ Имена и арность зависят от предметной области. Важна форма: кортеж + ограничения через уже введенные `F#` и `S#`.
76
+
77
+ Части кортежа называй через `D# := Pr#(D13)`.
78
+
79
+ ## Инварианты
80
+
81
+ Для функциональности отношения предпочитай `card`:
82
+
83
+ ```text
84
+ card(S1) = card(Pr1,2(S1))
85
+ ```
86
+
87
+ Это заменяет длинные `∀d1,d2∈S1 ...`. Оставляй `∀` / `∃`, только если выражение нельзя задать через множества, проекции, фильтры, `card`.
40
88
 
41
- Если повторяется цепочка вроде `Pr2(Fi1[D](S7))`, введи промежуточный терм или уточни конвенцию/аксиому для `S7`.
89
+ ## Производные термы
42
90
 
43
- ## Аксиомы
91
+ Если условие уже задано на `S#` или центральном `D#`, производный терм обычно:
44
92
 
45
- `A#` — логическое требование к модели. Используй аксиомы, чтобы:
93
+ - `Prk(…)` / `Pri,j(…)`;
94
+ - `Fi*k[{…}](…)`;
95
+ - `D{ξ∈… | F[ξ] = …}`;
96
+ - `card(F[ξ]) = 1`.
46
97
 
47
- - фиксировать смысл `S#`;
48
- - задавать уникальность, тотальность, непересечение, порядок, область и диапазон;
49
- - оправдывать `debool(...)`: внутреннее множество должно быть гарантированно одноэлементным.
98
+ Перед `D{x∈… | ∃d1∈… ∃d2∈…}` проверь, нельзя ли взять `Pr` от уже введенного отношения.
50
99
 
51
- ## Проверка на маленькой модели
100
+ ## Проверка на маленькой КМ
52
101
 
53
- Когда семантика определения не очевидна, используй концептуальную модель как тестовый стенд: задай минимальные значения для `X#`, `C#`, `S#` и вычисли проверяемые `D#`, `F#`, `P#`, `A#`.
102
+ Если семантика не очевидна, собери минимальную модель: значения для `X#`, `C#`, `S#`; затем вычисли целевые `D#`, `F#`, `P#`, `A#`.
54
103
 
55
- Это особенно полезно для проекций, фильтров, `red`, `bool` / `debool` и аксиом. Если проверка важна для будущих изменений, перенеси ее в скрипт-тест: собрать маленькую сессию, задать значения неопределяемых конституент, вычислить целевые конституенты и проверить не только `success`, но и ожидаемое `value`.
104
+ Особенно проверяй проекции, фильтры, `red`, `bool` / `debool`, аксиомы. Для важной проверки сделай скрипт-тест: сессия + значения неопределяемых конституент + проверка `success` и ожидаемого `value`.
56
105
 
57
- Подробный цикл: `MODEL-TESTING.md`.
106
+ Цикл: `MODEL-TESTING.md`.
58
107
 
59
108
  ## Быстрое ревью
60
109
 
61
- - Атрибутивная экспликация не смешана с родоструктурной без явного запроса пользователя.
62
- - Не добавляй проверки принадлежности к собственной типизации: если `x` уже объявлен в `X1`, `x ∈ X1` избыточно.
63
- - Покрыты главные предметные сущности, роли, отношения и утверждения.
64
- - Слои идут так: `X#`/`C#` → `S#` → простые `D#` → сложные `D#`/`F#`/`P#` → `A#`/`T#`.
65
- - У каждой аксиомы понятная цель.
66
- - Частые падения аксиом в модели указывают на ошибку данных или семантики схемы.
67
- - Сомнительные выражения проверены на маленькой КМ, если есть показательные тестовые данные.
110
+ - Атрибутивная и родоструктурная экспликации не смешаны без запроса.
111
+ - Нет проверки принадлежности к собственной типизации: `x∈X1` избыточно, если `x` уже объявлен в `X1`.
112
+ - Покрыты главные сущности, роли, отношения, утверждения.
113
+ - Повторяющиеся отборы вынесены в `F#`.
114
+ - Каждая аксиома имеет понятную цель.
115
+ - Сомнительная семантика проверена на маленькой КМ при наличии тестовых данных.
68
116
 
69
117
  ## Рабочий порядок
70
118
 
71
- 1. Собери словарь предметной области.
72
- 2. Добавь `X#` и `C#` с конвенциями.
73
- 3. Добавь ключевые `S#` с типизацией и конвенцией.
74
- 4. Назови важные компоненты через `D#`: `Pr*`, `pr*`, `red`.
75
- 5. Добавляй выводимые `D#`, `F#`, `P#` маленькими шагами.
76
- 6. Добавь `A#` и `T#` по необходимости.
77
- 7. Перед upsert проверяй `analyzeExpression`.
78
- 8. Для сомнительной семантики собери маленькую КМ и вычисли ожидаемые значения.
119
+ 1. Собери словарь: базовые понятия, ключевые отношения, сценарий синтеза.
120
+ 2. Добавь `X#`, `C#` с конвенциями из источника.
121
+ 3. Добавь базовые `S#`: трансформация, перевод, допускание, выбор, цели, субъекты.
122
+ 4. Проверь, что базовые понятия независимы и не выводятся друг из друга.
123
+ 5. Добавь `A#` на структуры: `card`, покрытие `Pr1,2(S#)=…`, принадлежность выбора.
124
+ 6. Введи `F#` для типовых запросов.
125
+ 7. Производные понятия строй через `Pr*`, `Fi*`, `F#` от центрального `D#` и базовых `S#`.
126
+ 8. Перед каждым upsert запускай `analyzeExpression`.
127
+ 9. Для сомнительной семантики собери маленькую КМ (`MODEL-TESTING.md`).
package/docs/CONSTITUENTA.md CHANGED
@@ -2,21 +2,23 @@
2
2
 
3
3
  Читай перед `addOrUpdateConstituenta`.
4
4
 
5
- ## Поля черновика
5
+ ## Поля
6
6
 
7
7
  - `id` — стабильный id внутри сессии.
8
8
  - `alias` — имя вида `X1`, `D5`, `F2`; префикс должен совпадать с `cstType`.
9
9
  - `cstType` — роль конституенты.
10
10
  - `definitionFormal` — формальное определение; для `basic` и `constant` строго `''`.
11
- - `term` — естественно-языковое имя.
12
- - `definitionText` — текстовая интерпретация формулы.
13
- - `convention` — соглашение для неопределяемого понятия.
11
+ - `term` — термин в естественном языке, используется в текстовых определениях. Если обозначаются элементы множества, то пишется с маленькой буквы во множественном числе. Иначе с большой буквы в единственном.
12
+ - `definitionText` — текстовое определение, соответствующее формальному определению. Для простых выражений не указывается если совпадает с термином. Каждый используемый термин должен быть введен в схеме.
13
+ - `convention` — соглашение для неопределяемого понятия. Может использовать термины, не определенные в схеме.
14
14
 
15
15
  Пропущенные текстовые поля сохраняются как `''`. Пиши `term`, `definitionText`, `convention` на одном языке: в языке схемы или, для новой схемы, в языке запроса.
16
16
 
17
+ Не добавляй точку в конце текстовых полей.
18
+
17
19
  ## `cstType`
18
20
 
19
- - `nominal` / `N#` — номиноид. В родоструктурной экспликации не используется.
21
+ - `nominal` / `N#` — номиноид. В родоструктурной экспликации и формальных определениях не используется.
20
22
  - `basic` / `X#` — базисное множество; формула пустая.
21
23
  - `constant` / `C#` — константное множество; формула пустая.
22
24
  - `structure` / `S#` — родовая структура; формула задает типизацию.
@@ -26,13 +28,13 @@
26
28
  - `axiom` / `A#` — аксиома; нужна типизация `Logic`.
27
29
  - `statement` / `T#` — высказывание; нужна типизация `Logic`.
28
30
 
29
- `basic`, `constant`, `structure` можно интерпретировать через `setConstituentaValue`. `term`, `axiom`, `statement` вычисляются и напрямую не задаются.
31
+ В модели `basic`, `constant`, `structure` можно интерпретировать через `setConstituentaValue`. `term`, `axiom`, `statement` вычисляются и напрямую не задаются.
30
32
 
31
- ## `S#` и `D#`
33
+ ## Различие родовой структуры и терма
32
34
 
33
- `S#` — неопределяемая родовая структура. `definitionFormal: 'ℬ(X1×X1)'` описывает ступень элемента: множество пар над `X1`.
35
+ `S#` — неопределяемое понятие - родовая структура. Пример: `definitionFormal: 'ℬ(X1×X1)'` описывает ступень элемента: множество пар над `X1`.
34
36
 
35
- `D#` — терм. `definitionFormal: 'X1×X1'` строит полный декартов продукт.
37
+ `D#` — производное понятие - терм. Пример: `definitionFormal: 'X1×X1'` строит полный декартов продукт.
36
38
 
37
39
  Для бинарного отношения обычно нужно:
38
40
 
package/docs/DOMAIN.md CHANGED
@@ -12,13 +12,21 @@
12
12
  - **Типизация / ступень** — структура значений выражения: элемент, целое, кортеж, множество, `Logic`.
13
13
  - **Граф термов** — зависимости: конституента ссылается на другую в формальном определении.
14
14
 
15
+ ## Классификация понятий КС
16
+
17
+ - **Базовое (неопределяемое) понятие** — конституента, вводимая конвенцией (и при необходимости аксиомами), а не формальным определением. В родоструктурной экспликации: `X#`, `C#`, `S#`. Смысл задают `convention`, интерпретация и аксиомы.
18
+ - **Производное понятие** — конституента с формальным определением на RSLang: `D#`, `F#`, `P#` и связанные выводимые конструкции. Значение получают из определения при заданной интерпретации базовых понятий.
19
+ - **Ядро КС** — базовые понятия, аксиомы и производные понятия, необходимые для их формулировки.
20
+ - **Тело КС** — остальные конституенты схемы, не входящие в ядро.
21
+ - **Интерпретация** — соотнесение понятий КС с сущностями предметной области. В концептуальной модели задаётся значениями неопределяемых конституент и вычислением производных.
22
+
15
23
  ## Конституенты
16
24
 
17
25
  **Конституента** — часть КС. Главное для агента: `alias`, `cstType`, `definitionFormal`, `term`, `definitionText`, `convention`. `comment` — комментарий и пояснения разработчика схемы, полезно для контекста.
18
26
 
19
27
  - `N#` — **номиноид**: словарная сущность. В родоструктурной экспликации не используется.
20
28
  - `X#` — **базисное множество**: неопределяемое понятие, формула пустая.
21
- - `C#` — **константное множество**: неопределяемое множество для арифметики и порядка, формула пустая.
29
+ - `C#` — **константное множество**: неопределяемое понятие для арифметики и порядка, формула пустая.
22
30
  - `S#` — **родовая структура**: неопределяемое структурное понятие; формула задает типизацию.
23
31
  - `D#` — **терм**: определяемое понятие; формула вычисляет значение.
24
32
  - `F#` — **терм-функция**: параметризованный терм.
package/docs/MODEL-TESTING.md CHANGED
@@ -16,7 +16,7 @@
16
16
  1. Создай отдельную `createSession` или изолированную копию текущей сессии.
17
17
  2. Добавь только нужные поставщики: `X#`, `C#`, `S#` и проверяемые `D#` / `F#` / `P#` / `A#`.
18
18
  3. Проверь формулы через `analyzeExpression` и `addOrUpdateConstituenta`.
19
- 4. Задай значения базисов и структур через `setConstituentaValue` или `setConstituentaValues`.
19
+ 4. Задай значения базовых понятий через `setConstituentaValue` или `setConstituentaValues`.
20
20
  5. Вычисли проверяемую формулу через `evaluateExpression` или сохраненную конституенту через `evaluateConstituenta`.
21
21
  6. Сравни результат с ожидаемым значением; если есть несколько зависимых определений, запусти `recalculateModel`.
22
22
 
@@ -32,7 +32,13 @@ const TUPLE_ID = -111;
32
32
  tool.setConstituentaValues(sessionId, {
33
33
  items: [
34
34
  { target: 1, value: { 0: 'ann', 1: 'bob', 2: 'cat' } },
35
- { target: 2, value: [[TUPLE_ID, 0, 1], [TUPLE_ID, 0, 2]] }
35
+ {
36
+ target: 2,
37
+ value: [
38
+ [TUPLE_ID, 0, 1],
39
+ [TUPLE_ID, 0, 2]
40
+ ]
41
+ }
36
42
  ]
37
43
  });
38
44
  ```
package/docs/PORTAL-API.md CHANGED
@@ -28,4 +28,5 @@
28
28
 
29
29
  - Не парси HTML SPA.
30
30
  - Не переноси UI query/hash вроде `?tab=editor` в REST.
31
+ - Не запрашивай UI напрямую, используй преобразованные API запросы.
31
32
  - Не запрашивай `/details`, если нужны только метаданные.
package/docs/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  ## Какой файл читать
6
6
 
7
- - **DOMAIN.md** — термины Portal: конституента, концептуальная схема/модель, ОСС, синтез.
7
+ - **DOMAIN.md** — термины Portal: конституента, базовые и производные понятия, ядро/тело КС, интерпретация, ОСС, синтез.
8
8
  - **CONCEPTUAL-SCHEMA.md** — проектирование и ревью концептуальных схем.
9
9
  - **CONSTITUENTA.md** — структура и правила конституент.
10
10
  - **SYNTAX.md** — операторы, кванторы, функции и примеры выражений.
package/docs/TYPIFICATION.md CHANGED
@@ -29,16 +29,10 @@
29
29
 
30
30
  ## `AnalysisResult.type`
31
31
 
32
- `type` приходит как JSON анализатора: `Record<string, unknown> | null`.
33
-
34
- Правила:
35
-
36
32
  1. Сначала проверь `analysis.success === true` и `analysis.type !== null`.
37
33
  2. Не разбирай объект вручную; используй helpers из `@rsconcept/domain`.
38
34
  3. `valueClass` уточняет вычислимость: `Value`, `Property`, `Invalid`.
39
35
 
40
- Полезные API: `TypeID`, `TypePath`, `makeTypePath`, `parseTypeText(...)`.
41
-
42
36
  ## `S#` и `D#`
43
37
 
44
38
  - У `structure` (`S#`) `definitionFormal` читается как типизация. `ℬ(X1×X1)` описывает множество пар.
@@ -52,14 +46,14 @@
52
46
 
53
47
  Требуют подходящую ступень:
54
48
 
55
- - `red(S)` — нужно `S : ℬ(ℬ(H))`.
49
+ - `red(S)` — нужно `S : ℬℬ(H)`.
56
50
  - `debool(S)` — нужно одноэлементное множество.
57
51
  - `pr1(tuple)`, `Pr1(S)` — нужна достаточная арность.
58
- - `Fi1[D](S)` — `D` должен соответствовать выбранной проекции.
52
+ - `Fi1[a](S)` — `a` должен соответствовать выбранной проекции.
59
53
 
60
54
  ## Частые ошибки
61
55
 
62
56
  - `debool(S)` без гарантии синглетона.
63
57
  - `pr3((a, b))`: индекс вне арности.
64
- - `Fi1,2[D](S)`: параметр `D` не совпал с двумя проекциями.
58
+ - `Fi1,2[a](S)`: параметр `a` не совпал с двумя проекциями.
65
59
  - `A#` и `T#` не имеют `Logic`: будет `expectedLogic`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rsconcept/rstool",
3
- "version": "0.4.0",
3
+ "version": "0.5.1",
4
4
  "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.",
5
5
  "license": "MIT",
6
6
  "author": "IRBorisov",
package/skills/rstool-helper/EXAMPLES.md CHANGED
@@ -4,8 +4,6 @@ Short examples for agents. For full scripts, see `../../examples/`.
4
4
 
5
5
  ## Minimal Session
6
6
 
7
- `S1` carries typification `ℬ(X1×X1)` for relation pairs. `D1` computes `Pr1(S1)`. Do not put bare `X1×X1` on a `term` when you mean a relation structure.
8
-
9
7
  ```ts
10
8
  import { CstType, RSToolAgent } from '@rsconcept/rstool';
11
9
 
@@ -48,58 +46,7 @@ if (!analysis.success) {
48
46
  }
49
47
  ```
50
48
 
51
- Fix the reported `from` / `to` range, then re-run analysis. Do not retry unchanged input.
52
-
53
- ## Wrapper Client
54
-
55
- Use the wrapper when the agent talks to a separate `rstool-wrapper` process.
56
-
57
- ```ts
58
- import { CstType } from '@rsconcept/rstool';
59
- import { RSToolWrapperClient } from '@rsconcept/rstool/wrapper';
60
-
61
- const client = new RSToolWrapperClient();
62
- await client.waitUntilReady();
63
-
64
- const { sessionId } = await client.call<{ sessionId: string }>('createSession');
65
-
66
- await client.call('addOrUpdateConstituenta', {
67
- sessionId,
68
- input: {
69
- draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
70
- }
71
- });
72
-
73
- const diagnostics = await client.call('listDiagnostics', { sessionId });
74
- console.log(diagnostics);
75
-
76
- await client.close();
77
- ```
78
-
79
- Manual stdio is one JSON request per line:
80
-
81
- ```jsonl
82
- { "id": "1", "method": "createSession", "params": {} }
83
- { "id": "2", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 1, "alias": "X1", "cstType": "basic", "definitionFormal": "" } } } }
84
- ```
85
-
86
- ## Export / Import
87
-
88
- ```ts
89
- const payload = tool.exportSession(sessionId);
90
- const restored = tool.importSession(payload);
91
- ```
92
-
93
- Export includes session state and model values.
94
-
95
- To create files the user can upload to an existing Portal object:
96
-
97
- ```ts
98
- const schemaJson = tool.exportPortalSchema(sessionId);
99
- const modelJson = tool.exportPortalModel(sessionId);
100
- ```
101
-
102
- Use `schemaJson` on a schema page and `modelJson` on a model page via **Load from JSON**.
49
+ Fix the reported `from` / `to` range, then re-run analysis. Maybe rethink the whole definition or split into multiple constituents
103
50
 
104
51
  ## Evaluation
105
52
 
@@ -162,20 +109,62 @@ if (!result.success || result.status !== EvalStatus.HAS_DATA || JSON.stringify(r
162
109
 
163
110
  Use this pattern for tests that protect important definitions. Full kinship model: `../../examples/build-kinship-rsmodel.ts`. More notes: `../../docs/MODEL-TESTING.md`.
164
111
 
112
+ ## Wrapper Client
113
+
114
+ Use the wrapper when the agent talks to a separate `rstool-wrapper` process.
115
+
116
+ ```ts
117
+ import { CstType } from '@rsconcept/rstool';
118
+ import { RSToolWrapperClient } from '@rsconcept/rstool/wrapper';
119
+
120
+ const client = new RSToolWrapperClient();
121
+ await client.waitUntilReady();
122
+
123
+ const { sessionId } = await client.call<{ sessionId: string }>('createSession');
124
+
125
+ await client.call('addOrUpdateConstituenta', {
126
+ sessionId,
127
+ input: {
128
+ draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
129
+ }
130
+ });
131
+
132
+ const diagnostics = await client.call('listDiagnostics', { sessionId });
133
+ console.log(diagnostics);
134
+
135
+ await client.close();
136
+ ```
137
+
138
+ Manual stdio is one JSON request per line:
139
+
140
+ ```jsonl
141
+ { "id": "1", "method": "createSession", "params": {} }
142
+ { "id": "2", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 1, "alias": "X1", "cstType": "basic", "definitionFormal": "" } } } }
143
+ ```
144
+
145
+ ## Export / Import
146
+
147
+ ```ts
148
+ const payload = tool.exportSession(sessionId);
149
+ const restored = tool.importSession(payload);
150
+ ```
151
+
152
+ Export includes session state and model values.
153
+
154
+ To create files the user can upload to an existing Portal object:
155
+
156
+ ```ts
157
+ const schemaJson = tool.exportPortalSchema(sessionId);
158
+ const modelJson = tool.exportPortalModel(sessionId);
159
+ ```
160
+
161
+ Use `schemaJson` on a schema page and `modelJson` on a model page via **Load from JSON**.
162
+
165
163
  ## Common mistakes
166
164
 
167
- - `definitionFormal: 'Z'` on `basic` / `constant` → `definitionNotAllowed`.
168
- - `D1` uses `D2` before `D2` exists → global not typed / undeclared.
169
165
  - Wrong `cstType` in `analyzeExpression` → role-specific errors.
170
166
  - `term` with `X1×X1` for a relation → full Cartesian product, not relation typification.
171
167
  - `structure` with `Pr1(S1)` → wrong role; projections belong on `term` / `function`.
168
+ - Same long `∃d1…∃dn` chain in many `D#` → define one central `D#` and use `Pr*` / `F#`.
172
169
  - `setConstituentaValue` on `term`, `axiom`, or `statement` → cannot set computed constituents directly.
173
170
  - Evaluation before base bindings → missing value, empty result, or evaluation failure.
174
-
175
- ## Fix Syntax
176
-
177
- 1. `analyzeExpression` with the broken fragment and correct `cstType`.
178
- 2. Read `{ code, from, to, params }`.
179
- 3. Edit the substring of `definitionFormal` at those offsets.
180
- 4. Re-run analysis.
181
- 5. Upsert with the same `id` / `alias`.
package/skills/rstool-helper/GUIDE.md CHANGED
@@ -29,37 +29,21 @@ Paths are relative to this file.
29
29
 
30
30
  ## Workflow
31
31
 
32
+ Use this when editing or checking schemas and models.
33
+
32
34
  1. `createSession`.
33
- 2. Add `basic` (`X#`) and `constant` (`C#`) with `definitionFormal: ''`.
35
+ 2. Develop schema - add constituents with proper type and attributes.
34
36
  3. Add dependencies before dependents.
35
37
  4. Use `analyzeExpression` before upsert when unsure.
36
- 5. When unsure about semantics, build a tiny conceptual model and evaluate test data.
37
- 6. Fix diagnostics by `from` / `to` range in `definitionFormal`.
38
- 7. `commitStep` when the state is coherent.
39
- 8. Set base/model values with `setConstituentaValue(s)`.
40
- 9. Evaluate with `evaluateExpression`, `evaluateConstituenta`, or `recalculateModel`.
41
- 10. Persist with `exportSession` / `importSession`.
42
- 11. For user-uploadable Portal files, use `exportPortalSchema` for schema JSON or `exportPortalModel` for model JSON.
43
-
44
- ## Portal REST
45
-
46
- rstool never calls Portal REST itself. Fetch live data outside rstool, then import constituents with `addOrUpdateConstituenta`.
47
-
48
- - UI host: `https://portal.acconcept.ru`.
49
- - API host: `https://api.portal.acconcept.ru`.
50
- - Useful reads: `/api/rsforms/{id}`, `/api/rsforms/{id}/details`, `/api/library/{id}/versions/{v}`, `/api/oss/{id}`, `/api/models/{id}`, `/schema`.
51
- - Do not scrape SPA HTML or reuse UI query params like `?tab=`.
38
+ 5. Fix diagnostics by `from` / `to` range in `definitionFormal`.
39
+ 6. When unsure about semantics, build a tiny conceptual model and evaluate test data.
52
40
 
53
- ## Syntax Cheatsheet
41
+ - Set base/model values with `setConstituentaValue(s)`.
42
+ - Evaluate with `evaluateExpression`, `evaluateConstituenta`, or `recalculateModel`.
54
43
 
55
- - Globals: `X1`, `C1`, `S1`, `D1`, `F1`, `P1`, `A1`, `T1`, `N1`, `R1`.
56
- - Locals: `x`, `ξ`, `μ2`.
57
- - Literals: `42`, `Z`, `∅`.
58
- - Set expressions: `∪`, `∩`, `\`, `∆`, `×`, `ℬ(...)`, tuples, `Pr*`, `Fi*`.
59
- - Logic: `¬`, `&`, `∨`, `⇒`, `⇔`, `∀`, `∃`, `=`, `≠`, `<`, `∈`, `⊆`.
60
- - Parameterized expressions: `[arg1∈H1, arg2∈H2] body`.
61
-
62
- Read tool output; do not infer types by inspection.
44
+ 7. `commitStep` when the state is coherent.
45
+ 8. Persist with `exportSession` / `importSession`.
46
+ 9. For user-uploadable Portal files, use `exportPortalSchema` for schema JSON or `exportPortalModel` for model JSON.
63
47
 
64
48
  ## Diagnostics Loop
65
49
 
@@ -76,19 +60,9 @@ Read tool output; do not infer types by inspection.
76
60
  3. Derived constituents in topological order.
77
61
  4. Axioms and statements after their references.
78
62
 
79
- ## Natural-Language Fields
80
-
81
- Keep `term`, `definitionText`, and `convention` in one language.
82
-
83
- - Extending a schema: use the schema's existing language.
84
- - New schema: use the user's request language.
85
-
86
63
  ## Checklist
87
64
 
88
65
  - [ ] `sessionId` tracked.
89
- - [ ] `basic` / `constant` formals are empty.
90
- - [ ] Dependencies exist before upsert.
91
66
  - [ ] `cstType` matches the role.
67
+ - [ ] Check schema and fix errors before showing result.
92
68
  - [ ] Diagnostics handled before commit/export.
93
- - [ ] Ambiguous semantics checked on a small model when data examples are available.
94
- - [ ] Base values set before evaluation.
package/skills/rstool-helper/REFERENCE.md CHANGED
@@ -34,8 +34,8 @@
34
34
  ```ts
35
35
  {
36
36
  id: number; // stable id within session
37
- alias: string; // e.g. "D1", "X1"
38
- cstType: CstType; // see GUIDE.md table
37
+ alias: string;
38
+ cstType: CstType;
39
39
  definitionFormal: string;
40
40
  term?: string;
41
41
  definitionText?: string;
@@ -62,7 +62,7 @@ All default to `''` when omitted.
62
62
  ### Model and evaluation types
63
63
 
64
64
  ```ts
65
- type RSToolValue = number | RSToolValue[]; // runtime value (sets, tuples, logic 0/1)
65
+ type RSToolValue = number | RSToolValue[]; // runtime value
66
66
  type BasicBinding = Record<number, string>; // base-set element labels
67
67
 
68
68
  interface SessionModelState {
@@ -115,34 +115,32 @@ Example chain:
115
115
  ```ts
116
116
  interface AnalysisResult {
117
117
  success: boolean;
118
- type: Record<string, unknown> | null; // typification tree
118
+ type: Record<string, unknown> | null;
119
119
  valueClass: 'value' | 'property' | null;
120
120
  diagnostics: { code: number; from: number; to: number; params?: string[] }[];
121
121
  }
122
122
  ```
123
123
 
124
- ## RS language — conceptual model
125
-
126
- - **Typification**: structure type of an expression; grades include elements (`Xi`, `Ci`), `Z`, tuples `(H1×…×Hn)`, sets `ℬ(H)`, logic `Logic`, parameterized `Hr 🠔 [H1,…,Hi]`. On `structure` (`S#`), `definitionFormal` **is** the typification. On `term` (`D#`), typification is **inferred from** the definition.
127
- - **Term graph**: directed dependencies between constituenta via alias references in definitions.
128
- - **`S#` vs `D#`**: same `×` token — in `ℬ(X1×X1)` on `S#` it forms a **grade** (pair type); in `X1×X1` on `D#` it is the **Cartesian product** (all pairs). Relations: `S#` + `convention`, then derived `D#` (`Pr1(S1)`, …).
124
+ ## RS language
129
125
 
130
126
  Intro (help): language is FOL-based; set vs logic expression split; parameterized templates for term/predicate functions.
131
127
 
132
- ## Grammar tokens (selected)
128
+ - **Typification**: structure type of an expression; grades include elements (`Xi`, `Ci`), `Z`, tuples `(H1×…×Hn)`, sets `ℬ(H)`, logic `Logic`, parameterized `Hr 🠔 [H1,…,Hi]`. On `structure` (`S#`), `definitionFormal` **is** the typification. On `term` (`D#`), typification is **inferred from** the definition.
129
+
130
+ ## Grammar tokens
133
131
 
134
132
  From `rslang.grammar`:
135
133
 
136
- | Category | Tokens / forms |
137
- | ---------------------- | ---------------------------------------------------------- |
138
- | Globals | `X`, `C`, `S`, `D`, `A`, `T`, `N` + digits (`Global` rule) |
139
- | Functions / predicates | `F<n>`, `P<n>` |
140
- | Radicals | `R<n>` |
141
- | Locals | `_a-zα-ω` + optional digits |
142
- | Logic | `¬` `∀` `∃` `⇔` `⇒` `∨` `&` |
143
- | Sets | `ℬ` `∪` `\` `∆` `∩` `×` `∈` `∉` `⊆` `⊂` … |
144
- | Ops | `Pr`, `pr`, `Fi`, `card`, `bool`, `debool`, `red` |
145
- | Literals | digits, `Z`, `∅` |
134
+ | Category | Tokens / forms |
135
+ | ---------------------- | ----------------------------------------------------- |
136
+ | Globals | `X`, `C`, `S`, `D`, `A`, `T` + digits (`Global` rule) |
137
+ | Functions / predicates | `F<n>`, `P<n>` |
138
+ | Radicals | `R<n>` |
139
+ | Locals | `_a-zα-ω` + optional digits |
140
+ | Logic | `¬` `∀` `∃` `⇔` `⇒` `∨` `&` |
141
+ | Sets | `ℬ` `∪` `\` `∆` `∩` `×` `∈` `∉` `⊆` `⊂` … |
142
+ | Ops | `Pr`, `pr`, `Fi`, `card`, `bool`, `debool`, `red` |
143
+ | Literals | digits, `Z`, `∅` |
146
144
 
147
145
  Full grammar pointers and precedence notes: `docs/GRAMMAR-REF.md`.
148
146
 
@@ -167,7 +165,7 @@ Standalone agents should consult the bundled distilled docs (`docs/*.md` inside
167
165
  | Portal REST API | `docs/PORTAL-API.md` |
168
166
  | Grammar tokens / precedence | `docs/GRAMMAR-REF.md` |
169
167
 
170
- ## Error codes (rstool-relevant)
168
+ ## Error codes
171
169
 
172
170
  rstool re-exports `RSErrorCode.definitionNotAllowed` (`0x8862`) for base/constant violations.
173
171
 
@@ -197,7 +195,5 @@ For **Load from JSON** on an existing Portal schema or model:
197
195
  - `exportPortalSchema(sessionId)` — schema file
198
196
  - `exportPortalModel(sessionId)` — model file
199
197
 
200
- Both return `contract_version` `1.0.0` plus required `title`, `alias`, `description`, and `items`. Schema files may include `attribution`. Values come from `state.title`, `state.alias`, and `state.comment` (empty fields fall back to `Conceptual schema` / `SCHEMA` or `Conceptual model` / `MODEL` and `""`).
201
-
202
198
  - Schema `items[]`: versioned constituent fields (`cst_type`, `definition_formal`, `term_raw`, …).
203
199
  - Model `items[]`: `{ id, type, value }` per binding.
package/skills/rstool-helper/SKILL.md CHANGED
@@ -1,12 +1,10 @@
1
1
  ---
2
2
  name: rstool-helper
3
3
  description: >-
4
- RS language and @rsconcept/rstool for agents. After npm install, read GUIDE and
5
- docs from node_modules. If the entry skill is not installed in the project yet,
6
- follow skills/INSTALL.md in this package.
4
+ RS language, formal definitions and conceptual schema design for agents. Read GUIDE and docs from node_modules.
7
5
  ---
8
6
 
9
- # rstool-helper (npm install)
7
+ # rstool-helper
10
8
 
11
9
  Thin **entry** skill. Full guide and docs stay in the package — use the Read tool on the paths below (from the project root).
12
10