@rsconcept/rstool 0.4.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ Agent-facing library for **incremental RSForm construction**, **RSLang expressio
 
 ## Agent skill
 
-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.
+RS language + rstool workflows for agents: `skills/rstool-helper/` (`GUIDE.md`, `REFERENCE.md`, `EXAMPLES.md`) and `docs/` (`DOMAIN.md`, `CONCEPTUAL-SCHEMA.md` for relation-first KS design, `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.
 
 ## Install
 

package/docs/CONCEPTUAL-SCHEMA.md

@@ -9,15 +9,7 @@
 - Добавляй понятие, если оно дает новый критерий, роль, отношение, инвариант или правило.
 - Если пользователь постоянно переформулирует одно различие, введи отдельную конституенту.
 
-## Текстовые поля
-
-`term`, `definitionText`, `convention` держи в языке схемы и в ее словаре.
-
-- `term` — короткое имя понятия.
-- `definitionText` — текстовая интерпретация формального определения.
-- `convention` — соглашение для неопределяемого понятия.
-
-Перед записью `definitionText` проверь существительные: важный предметный термин должен быть введен как `N#`, `X#`, `C#`, `S#` или `D#`.
+Подробнее про структуру и поля конституент см. в [CONSTITUENTA.md](./CONSTITUENTA.md).
 
 ## Номиноиды и атрибутирование
 
@@ -25,7 +17,7 @@
 
 Атрибутирование связывает номиноид с другими конституентами через атрибуты. Это отдельная атрибутивная экспликация, не замена `S#`, `D#`, `A#` в родоструктурной экспликации.
 
-Правило для `rstool`: не смешивай атрибутивную и родоструктурную экспликацию. Используй `N#` как словарную опору, но не превращай атрибуты в RS-формулы и не добавляй атрибутивные связи, если пользователь явно не просит совместить эти способы.
+Правило для `rstool`: не смешивай атрибутивную и родоструктурную экспликацию если явно не указано пользователем.
 
 ## Родовые структуры
 
@@ -34,19 +26,64 @@
 Паттерн для отношения:
 
 1. `X1` — базисное множество.
-2. `S1: ℬ(X1×X1)` — отношение; порядок пары описан в `convention`.
+2. `S1: ℬ(X1×X1)` — отношение; предметное пояснение в `convention`.
 3. `D# := Pr1(S1)`, `D# := Pr2(S1)` — именованные компоненты.
-4. Сложные термы строятся поверх этих `D#`.
+4. Сложные термы строятся поверх этих `D#` и `S#`.
+
+Если повторяется цепочка вроде `Pr2(Fi1[D](S7))`, введи промежуточный терм или функцию `F#`.
+
+## Подход relation-first
+
+Используй при объединении нескольких исходных КС в одну предметную модель и при появлении длинных цепочек `∃d1…∃dn` в разных термах.
+
+### Семантическая лестница
+
+Строй схему слоями; каждый следующий слой ссылается только на предыдущие:
+
+| Слой | Роль                   | Что вводить                                                                                  |
+| :--- | :--------------------- | :------------------------------------------------------------------------------------------- |
+| 1    | Базис                  | `X#`, `C#` — пустой `definitionFormal`, смысл в `convention` / `definitionText` из источника |
+| 2    | Структуры              | `S#` — типизация `ℬ(…×…)` и конвенция на кортеж                                              |
+| 3    | Инварианты             | `A#` — короткие ограничения (см. ниже про `card`)                                            |
+| 4    | Параметрический доступ | `F#` — «локальный API»: `[α∈…] Pr*(Fi*[…](S#))`                                              |
+| 5    | Центральное отношение  | один `D#` (или `S#` с конвенцией), задающий полную траекторию синтеза                        |
+| 6    | Витрина понятий        | `D#` через `Pr*`, `Fi*`, `card`, `red`; узкие `F#` для аналитики                             |
+
+### Центральное отношение
+
+Когда в тексте описан единый сценарий, зафиксируй его **одним** объектом:
+
+```text
+D13 ::= I{(α, ξ1, τ, ξ2, β1, β2, ρ, ξ3) |
+  α∈S6; ξ1∈X2; τ∈F7[α,ξ1]; …; ξ3∈S3
+}
+```
+
+(Имена и арность — по предметной области; важна форма: кортеж + ограничения через уже введённые `F#` и `S#`.)
+
+Далее можешь дать название необходимым частям кортежа с помощью `D#` через `Pr#`
+
+### Инварианты: `card` вместо длинных `∀`
+
+Для функциональности отношения удобно:
+
+```text
+card(S1) = card(Pr1,2(S1))
+```
+
+Эквивалентно идее `∀d1,d2∈S1 ...`
+
+Оставляй `∀`/`∃`, когда не получается заменить на теоретико-множественные и структурные конструкции.
 
-Если повторяется цепочка вроде `Pr2(Fi1[D](S7))`, введи промежуточный терм или уточни конвенцию/аксиому для `S7`.
+### Проекции вместо повторных кванторов
 
-## Аксиомы
+Если условие уже задано на `S#` или центральном `D#`, производный терм — это почти всегда:
 
-`A#` — логическое требование к модели. Используй аксиомы, чтобы:
+- `Prk(…)` / `Pri,j(…)`;
+- `Fi*k[{…}](…)`;
+- `D{ξ∈… | F[ξ] = …}` или `card(F[ξ]) = 1`.
 
-- фиксировать смысл `S#`;
-- задавать уникальность, тотальность, непересечение, порядок, область и диапазон;
-- оправдывать `debool(...)`: внутреннее множество должно быть гарантированно одноэлементным.
+Перед тем как писать `D{x∈… | ∃d1∈… ∃d2∈…}`, проверь: нельзя ли выразить через `Pr` от уже введённого отношения.
 
 ## Проверка на маленькой модели
 
@@ -61,18 +98,19 @@
 - Атрибутивная экспликация не смешана с родоструктурной без явного запроса пользователя.
 - Не добавляй проверки принадлежности к собственной типизации: если `x` уже объявлен в `X1`, `x ∈ X1` избыточно.
 - Покрыты главные предметные сущности, роли, отношения и утверждения.
-- Слои идут так: `X#`/`C#` → `S#` → простые `D#` → сложные `D#`/`F#`/`P#` → `A#`/`T#`.
-- У каждой аксиомы понятная цель.
+- Повторяющиеся отборы вынесены в `F#`, а не размазаны по термам.
+- У каждой аксиомы понятна цель.
 - Частые падения аксиом в модели указывают на ошибку данных или семантики схемы.
 - Сомнительные выражения проверены на маленькой КМ, если есть показательные тестовые данные.
 
 ## Рабочий порядок
 
-1. Собери словарь предметной области.
-2. Добавь `X#` и `C#` с конвенциями.
-3. Добавь ключевые `S#` с типизацией и конвенцией.
-4. Назови важные компоненты через `D#`: `Pr*`, `pr*`, `red`.
-5. Добавляй выводимые `D#`, `F#`, `P#` маленькими шагами.
-6. Добавь `A#` и `T#` по необходимости.
-7. Перед upsert проверяй `analyzeExpression`.
-8. Для сомнительной семантики собери маленькую КМ и вычисли ожидаемые значения.
+1. Собери словарь предметной области (базисы, ключевые отношения, сценарий синтеза).
+2. Добавь `X#` и `C#` с конвенциями из источника.
+3. Добавь базовые `S#` (трансформация, перевод, допускание, выбор, цели, субъекты).
+4. Добавь `A#` на структуры (`card`, покрытие `Pr1,2(S#)=…`, принадлежность выбора).
+5. Введи `F#` для типовых запросов.
+6. Производные понятия — `Pr*` / `Fi*` / `F#` от центрального `D#` и базовых `S#`.
+7. Узкие классификаторы (`для любой обстановки`, `для одного индивида`) — через `F#` и `card`/`=` с `X#`, не новые монолиты.
+8. Перед каждым upsert — `analyzeExpression`.
+9. Для сомнительной семантики — маленькая КМ (`MODEL-TESTING.md`).

package/docs/CONSTITUENTA.md

@@ -2,21 +2,23 @@
 
 Читай перед `addOrUpdateConstituenta`.
 
-## Поля черновика
+## Поля
 
 - `id` — стабильный id внутри сессии.
 - `alias` — имя вида `X1`, `D5`, `F2`; префикс должен совпадать с `cstType`.
 - `cstType` — роль конституенты.
 - `definitionFormal` — формальное определение; для `basic` и `constant` строго `''`.
-- `term` — естественно-языковое имя.
-- `definitionText` — текстовая интерпретация формулы.
-- `convention` — соглашение для неопределяемого понятия.
+- `term` — термин в естественном языке, используется в текстовых определениях. Если обозначаются элементы множества, то пишется с маленькой буквы во множественном числе. Иначе с большой буквы в единственном.
+- `definitionText` — текстовое определение, соответствующее формальному определению. Для простых выражений не указывается если совпадает с термином. Каждый используемый термин должен быть введен в схеме.
+- `convention` — соглашение для неопределяемого понятия. Может использовать термины, не определенные в схеме.
 
 Пропущенные текстовые поля сохраняются как `''`. Пиши `term`, `definitionText`, `convention` на одном языке: в языке схемы или, для новой схемы, в языке запроса.
 
+Не добавляй точку в конце текстовых полей.
+
 ## `cstType`
 
-- `nominal` / `N#` — номиноид. В родоструктурной экспликации не используется.
+- `nominal` / `N#` — номиноид. В родоструктурной экспликации и формальных определениях не используется.
 - `basic` / `X#` — базисное множество; формула пустая.
 - `constant` / `C#` — константное множество; формула пустая.
 - `structure` / `S#` — родовая структура; формула задает типизацию.
@@ -26,13 +28,13 @@
 - `axiom` / `A#` — аксиома; нужна типизация `Logic`.
 - `statement` / `T#` — высказывание; нужна типизация `Logic`.
 
-`basic`, `constant`, `structure` можно интерпретировать через `setConstituentaValue`. `term`, `axiom`, `statement` вычисляются и напрямую не задаются.
+В модели `basic`, `constant`, `structure` можно интерпретировать через `setConstituentaValue`. `term`, `axiom`, `statement` вычисляются и напрямую не задаются.
 
-## `S#` и `D#`
+## Различие родовой структуры и терма
 
-`S#` — неопределяемая родовая структура. `definitionFormal: 'ℬ(X1×X1)'` описывает ступень элемента: множество пар над `X1`.
+`S#` — неопределяемое понятие - родовая структура. Пример: `definitionFormal: 'ℬ(X1×X1)'` описывает ступень элемента: множество пар над `X1`.
 
-`D#` — терм. `definitionFormal: 'X1×X1'` строит полный декартов продукт.
+`D#` — производное понятие - терм. Пример: `definitionFormal: 'X1×X1'` строит полный декартов продукт.
 
 Для бинарного отношения обычно нужно:
 

package/docs/PORTAL-API.md

@@ -28,4 +28,5 @@
 
 - Не парси HTML SPA.
 - Не переноси UI query/hash вроде `?tab=editor` в REST.
+- Не запрашивай UI напрямую, используй преобразованные API запросы.
 - Не запрашивай `/details`, если нужны только метаданные.

package/docs/TYPIFICATION.md

@@ -29,16 +29,10 @@
 
 ## `AnalysisResult.type`
 
-`type` приходит как JSON анализатора: `Record<string, unknown> | null`.
-
-Правила:
-
 1. Сначала проверь `analysis.success === true` и `analysis.type !== null`.
 2. Не разбирай объект вручную; используй helpers из `@rsconcept/domain`.
 3. `valueClass` уточняет вычислимость: `Value`, `Property`, `Invalid`.
 
-Полезные API: `TypeID`, `TypePath`, `makeTypePath`, `parseTypeText(...)`.
-
 ## `S#` и `D#`
 
 - У `structure` (`S#`) `definitionFormal` читается как типизация. `ℬ(X1×X1)` описывает множество пар.
@@ -52,14 +46,14 @@
 
 Требуют подходящую ступень:
 
-- `red(S)` — нужно `S : ℬ(ℬ(H))`.
+- `red(S)` — нужно `S : ℬℬ(H)`.
 - `debool(S)` — нужно одноэлементное множество.
 - `pr1(tuple)`, `Pr1(S)` — нужна достаточная арность.
-- `Fi1[D](S)` — `D` должен соответствовать выбранной проекции.
+- `Fi1[a](S)` — `a` должен соответствовать выбранной проекции.
 
 ## Частые ошибки
 
 - `debool(S)` без гарантии синглетона.
 - `pr3((a, b))`: индекс вне арности.
-- `Fi1,2[D](S)`: параметр `D` не совпал с двумя проекциями.
+- `Fi1,2[a](S)`: параметр `a` не совпал с двумя проекциями.
 - `A#` и `T#` не имеют `Logic`: будет `expectedLogic`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsconcept/rstool",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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.",
   "license": "MIT",
   "author": "IRBorisov",

package/skills/rstool-helper/EXAMPLES.md

@@ -162,6 +162,52 @@ if (!result.success || result.status !== EvalStatus.HAS_DATA || JSON.stringify(r
 
 Use this pattern for tests that protect important definitions. Full kinship model: `../../examples/build-kinship-rsmodel.ts`. More notes: `../../docs/MODEL-TESTING.md`.
 
+## Relation-first synthesis (layered KS)
+
+Pattern for merging sub-schemas (transformation + transition + choice → stimulation). Reference: Portal `D01B03` / rsform `843`.
+
+1. **Structures** — one `S#` per mechanism, typification only:
+
+```text
+S1: ℬ(X1×X2×X1)   // transformation
+S2: ℬ(X2×X3×X2)   // transition
+S4: ℬ(X2×X1×X3)   // allowance (flat triple, not ℬ(X2×X1×ℬ(X3)))
+S5: ℬ(X1×ℬ(X3)×X3) // choice
+```
+
+2. **Axioms** — short invariants:
+
+```text
+A1: Pr1,2(S1) = X1×X2
+A2: card(S1) = card(Pr1,2(S1))
+A4: card(S5) = card(Pr1,2(S5))
+A5: ∀d∈S5 pr3(d)∈pr2(d)
+```
+
+3. **Functions** — parameterized access (reuse everywhere):
+
+```text
+F5[α,β] := Pr3(Fi1,2[{(β,α)}](S4))   // possible actions
+F7[α,ξ] := F6[α, F5[α,ξ]]            // chosen action in situation
+```
+
+4. **Central term** — one tuple relation, then projections:
+
+```text
+D13 ::= I{(α,ξ1,τ,ξ2,β1,β2,ρ,ξ3) | α∈S6; ξ1∈X2; τ∈F7[α,ξ1]; …; ξ3∈S3}
+D14 := Pr3(D13)   // stimuli
+D18 := Pr2(D13)   // initial situations
+```
+
+5. **Classifiers** — filter via `F#`, not a new `∃` chain:
+
+```text
+F8[α] := Pr2(Fi3[{α}](D13))
+D22 := D{ξ∈D14 | F8[ξ] = X2}   // stimulus valid in any situation
+```
+
+Upsert in dependency order; run `analyzeExpression` on `I{…}` before committing the central `D#`.
+
 ## Common mistakes
 
 - `definitionFormal: 'Z'` on `basic` / `constant` → `definitionNotAllowed`.
@@ -169,6 +215,10 @@ Use this pattern for tests that protect important definitions. Full kinship mode
 - Wrong `cstType` in `analyzeExpression` → role-specific errors.
 - `term` with `X1×X1` for a relation → full Cartesian product, not relation typification.
 - `structure` with `Pr1(S1)` → wrong role; projections belong on `term` / `function`.
+- Same long `∃d1…∃dn` chain in many `D#` → define one central `D#` and use `Pr*` / `F#`.
+- `S4: ℬ(X2×X1×ℬ(X3))` when you only need «individual allows actions» → prefer `ℬ(X2×X1×X3)` + `F5`.
+- `∀x∈A, ∀y∈B` → invalid; nest: `∀x∈A (∀y∈B (…))`.
+- Functional relation axiom as huge `∀⇒` → prefer `card(S)=card(Pr1,2(S))` when equivalent.
 - `setConstituentaValue` on `term`, `axiom`, or `statement` → cannot set computed constituents directly.
 - Evaluation before base bindings → missing value, empty result, or evaluation failure.
 

package/skills/rstool-helper/GUIDE.md

@@ -29,6 +29,8 @@ Paths are relative to this file.
 
 ## Workflow
 
+Use this when editing or checking schemas and models.
+
 1. `createSession`.
 2. Add `basic` (`X#`) and `constant` (`C#`) with `definitionFormal: ''`.
 3. Add dependencies before dependents.
@@ -41,26 +43,6 @@ Paths are relative to this file.
 10. Persist with `exportSession` / `importSession`.
 11. For user-uploadable Portal files, use `exportPortalSchema` for schema JSON or `exportPortalModel` for model JSON.
 
-## Portal REST
-
-rstool never calls Portal REST itself. Fetch live data outside rstool, then import constituents with `addOrUpdateConstituenta`.
-
-- UI host: `https://portal.acconcept.ru`.
-- API host: `https://api.portal.acconcept.ru`.
-- Useful reads: `/api/rsforms/{id}`, `/api/rsforms/{id}/details`, `/api/library/{id}/versions/{v}`, `/api/oss/{id}`, `/api/models/{id}`, `/schema`.
-- Do not scrape SPA HTML or reuse UI query params like `?tab=`.
-
-## Syntax Cheatsheet
-
-- Globals: `X1`, `C1`, `S1`, `D1`, `F1`, `P1`, `A1`, `T1`, `N1`, `R1`.
-- Locals: `x`, `ξ`, `μ2`.
-- Literals: `42`, `Z`, `∅`.
-- Set expressions: `∪`, `∩`, `\`, `∆`, `×`, `ℬ(...)`, tuples, `Pr*`, `Fi*`.
-- Logic: `¬`, `&`, `∨`, `⇒`, `⇔`, `∀`, `∃`, `=`, `≠`, `<`, `∈`, `⊆`.
-- Parameterized expressions: `[arg1∈H1, arg2∈H2] body`.
-
-Read tool output; do not infer types by inspection.
-
 ## Diagnostics Loop
 
 1. Check `analysis.success`.
@@ -76,19 +58,11 @@ Read tool output; do not infer types by inspection.
 3. Derived constituents in topological order.
 4. Axioms and statements after their references.
 
-## Natural-Language Fields
-
-Keep `term`, `definitionText`, and `convention` in one language.
-
-- Extending a schema: use the schema's existing language.
-- New schema: use the user's request language.
-
 ## Checklist
 
 - [ ] `sessionId` tracked.
-- [ ] `basic` / `constant` formals are empty.
-- [ ] Dependencies exist before upsert.
 - [ ] `cstType` matches the role.
+- [ ] Check schema and fix errors before showing result.
 - [ ] Diagnostics handled before commit/export.
-- [ ] Ambiguous semantics checked on a small model when data examples are available.
+- [ ] Ambiguous semantics checked on a small model.
 - [ ] Base values set before evaluation.