@rsconcept/rstool 1.7.1 → 2.0.0

package/docs/METHOD.md

@@ -0,0 +1,208 @@
+# Метод концептуализации
+
+Как строить КС, которая отвечает запросу пользователя, а не только проходит анализатор. Структура метода взята из учебника З. А. Кучкарова (далее Т1, Т2 — тома 1 и 2), определения и обозначения — из Portal ([DOMAIN.md](DOMAIN.md), корневой `CONTEXT.md`). Книга агенту не справочник: её буквы и устаревшие формулировки сюда уже переведены.
+
+Цитаты приводятся по изданию: З. А. Кучкаров. Методы концептуального анализа и синтеза в теоретическом исследовании и проектировании социально-экономических систем. Т. 1–2. 3-е изд. М.: Концепт, 2008. Права на текст принадлежат организации-издателю.
+
+## Основная мысль
+
+КС ценна не числом конституент и не отсутствием диагностик, а тем, что **выражает нужные понятия и различения**. Поэтому работа начинается с задачи и требований к схеме, а не со словаря источника, и каждое решение о ядре записывается.
+
+Готово = выполнены требования к выразительным средствам, различения разведены, инварианты выражены аксиомами, это подтверждено сценариями на КМ, и диагностики чисты. Чистые диагностики — необходимое, но не достаточное условие.
+
+## Таблица соответствия: книга → Portal
+
+| В книге                                                        | На Portal                                                        |
+| :------------------------------------------------------------- | :--------------------------------------------------------------- |
+| `D` — родовая структура                                        | `S#` — родовая структура                                         |
+| `T` — терм                                                     | `D#` — терм; `F#` / `P#` — терм- и предикат-функции              |
+| `A` — аксиома                                                  | `A#` — аксиома                                                   |
+| «теорема»                                                      | `T#` — высказывание (типа «теорема» на Portal нет)               |
+| основные множества                                             | базисные множества `X#`; константные `C#`; ступень `Z`           |
+| ступени, шкала множеств (Бурбаки)                              | типизация ЯРЭ ([TYPIFICATION.md](TYPIFICATION.md))               |
+| атрибутивная → теоретико-множественная → родоструктурная формы | одна запись на ЯРЭ; атрибутивная проверка — строка `via` в брифе |
+| документация на теорию                                         | бриф и журнал решений ([BRIEF.md](BRIEF.md))                     |
+| интерпретация в конце цикла                                    | сценарии на КМ с начала работы («сначала тест»)                  |
+
+Не переноси буквы книги в схему: книжный `D1` — это наш `S1`, книжный `T1` — наш `D1`.
+
+Журнал решений — прямое продолжение требования книги:
+
+> «Решение каждый раз фиксируется, и если оно меняется, то это должно отражаться в документации на теорию. Если теория, как и компьютерная программа, документируется плохо, то “модулей” становится очень много, вследствие этого теория становится неудерживаемой и неконтролируемой» — Т1 §1.2.7.
+
+## Подход: исследовательский и проектный
+
+Назначение схемы задаёт строгость проверок (поле `approach` брифа).
+
+| `approach`  | Что считается ответом на запрос                                                                                       | Строгость                                                                                          |
+| :---------- | :-------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |
+| `research`  | Термины источника получили точные определения; смешанное в тексте разведено; противоречия и пробелы источника названы | Различения обязательны. Элементы базисных множеств могут быть условными. «Сироты» — предупреждение |
+| `education` | Схема минимальна, каждое определение объяснимо, решения по ядру видны                                                 | Сценарий на каждое требование                                                                      |
+| `project`   | Покрыты сущности, роли, состояния и бизнес-правила; ядро пригодно для синтеза                                         | Позитивный и негативный сценарий у каждого инварианта; конвенции обязательны; «сироты» — ошибка    |
+
+При проектном подходе (ПО, ОСС) каждый элемент базисного множества должен быть дан фактически: в сценариях — реальные объекты. При исследовательском интерпретируются производные понятия; элементы базисных множеств могут быть условными.
+
+> «При проектном подходе мы должны реализовать то, что положили в схеме, каждый элемент схемы должен материализоваться… множество исходных понятий должно быть дано фактически. При исследовательском подходе… схемы получают интерпретацию только в части своих производных понятий» — Т1 §1.5.2.4.
+
+## Роли: методник и предметник
+
+Агент — **методник**: знает метод и язык, предлагает варианты. Пользователь — **предметник**: знает предметную область и решает спорное. Показанная предметнику гипотеза ядра порождает у него вопросы, которые он сам бы не задал («схемное увеличение»). Отсюда два раунда вопросов: до формализации и после гипотезы ядра.
+
+> «Нередко предметник-профессионал с удивлением обнаруживает, что на вопросы, возникшие из логики синтеза, они не знают ответа, что такие вопросы ранее у них не возникали… всегда возникает некое “схемное увеличение”, позволяющее рассмотреть подробнее детали» — Т1 §1.6.2.1.
+
+Правила вопросов:
+
+- раунд 1 — не больше 5 вопросов, раунд 2 — не больше 4;
+- у каждого вопроса — предложенный ответ и следствие для выразимости, чтобы пользователь мог просто подтвердить;
+- пользователь подтверждает бриф целиком; новый вопрос — только при появлении нового различения или требования;
+- если спросить нельзя (фоновый агент) — ответы записываются в `assumptions`, статус брифа `assumed`.
+
+## Этапы
+
+Маршрут по умолчанию, а не ритуал. Последовательность не алгоритмична: возврат к любому этапу разрешён, и инструмент проверки брифа подсказывает, куда вернуться. Для точечной правки этапы 1–2 сводятся к одной строке брифа.
+
+> «…определенной алгоритмической последовательности их применения в настоящее время нет… не надо воспринимать методные возможности как догму» — Т1 §1.2.1.1.
+
+### Этап 1. Постановка
+
+**Выделение предметной области** — через задачу и точку зрения. Объект исследования (`object`) и задача (`task`) пишутся одной-двумя фразами. Предметная область задаётся в основном **отрицательно**: что исключено (время, история, процедуры, психология, оплата…). У каждого ограничения — перечень понятий, которые из-за него станут **невыразимыми** (`restrictions[].inexpressible`). Пользователь видит цену ограничения до формализации.
+
+> «Определение может носить отрицательный характер, т.е. не прямо определять предмет концептуализации, а исключать то, что концептуализации подлежать не будет, “высекая”, таким образом, предметную область из неограниченного содержания» — Т1 §1.2.2.
+>
+> «…не будут различаться “бывшие”, “настоящие” и “будущие” отношения “начальник – подчиненный”. Таким образом, понятие “мой подчиненный, который является моим бывшим начальником” – невыразимо в этой теории» — Т2 §4.2.1.2.
+
+**Расчистка источника** — две сетки разметки текста:
+
+1. по статусу утверждения: определение; правило (ограничение); пример; термин без определения; оценочное или нерелевантное;
+2. по смысловым блокам: о чём фрагмент (сущность, роль, отношение, состояние, правило).
+
+Нерелевантное и оценочное («интерфейс должен быть удобным») в схему не идёт; исключённое по задаче — в `restrictions`. Расчистка — главное средство против пересказа источника.
+
+> «…необходимы разметка содержания по статусам и группировка частей по понятийным блокам. Для этого строятся две сетки: первая – по статусу, вторая – по основным содержательным блокам» — Т1 §1.2.3.
+
+**Требования к выразительным средствам** (`expressiveness`) — понятия, которые схема обязана выразить. Это то, ради чего схему просили. Каждое требование проверяемо: для него можно написать пример или контрпример. Ориентир из инженерии онтологий — competency questions.
+
+> «Исследователь должен знать, каковы будут выразительные возможности теории, с помощью которой он намерен решить выдвинутую им задачу» — Т1 §1.2.4.
+
+**Различения** (`distinctions`) — пары понятий, которые в запросе смешаны или легко смешиваются: «назначенный» и «написавший», «активная» и «просроченная выдача». Разнообразие различений — главная ценность схемы: она должна вскрыть различение там, где в запросе было одно неразличённое понятие.
+
+> «Основной целью концептуализации является вскрытие разнообразия там, где имеет место единственное, не различенное» — Т1 §1.2.17.
+
+**Инварианты** (`invariants`) — правила, которые схема должна выражать аксиомами.
+
+**Классификация** в требованиях (статусы, категории): одно основание, полнота, непересекаемость. Она даёт пару аксиом разбиения (`S2∪S3=X1 & S2∩S3=∅`), а не коды в `C#`.
+
+> «– на протяжении деления должно удерживаться одно основание; – результаты деления совокупности на классы должны полностью исчерпывать совокупность признаков; – классы… не должны иметь общих элементов… Аксиома 1. Каждый объект принадлежит какому-нибудь классу. Аксиома 2. Каждый объект попадает только в один класс» — Т1 §1.2.29.
+
+Гейт: задача, ограничения и невыразимое записаны; каждое требование и инвариант проверяемы; раунд 1 вопросов пройден, остальное — в допущениях; бриф `confirmed` или `assumed`.
+
+### Этап 2. Ядро
+
+Ядро выбирается **под требования**, а не под словарь, и проверяется на них **до формул**.
+
+**Исходные понятия как гипотеза.** Каждое кандидат-неопределяемое понятие проверяется: не являются ли два кандидата видами одного рода? Вопрос «может ли начальник быть подчинённым?» ведёт к более высокой абстракции «люди» с отношением подчинения вместо двух базисных множеств. Признак: интерпретации двух `X#` пересекаются, или требование связывает их элементы как одно и то же лицо.
+
+> «Эту гипотезу нужно проверить следующим образом: могут ли начальники сами быть подчиненными по отношению к другим, и, наоборот, подчиненные сами быть начальниками? Известное содержание однозначно говорит, что могут… существует более высокая абстракция, чем начальник – подчиненный» — Т2 §4.2.1.4.
+
+**Родовое, а не видовое.** Если положить вид вместо рода, теряются остальные виды. Пример: однозначная функция там, где нужно отношение; симметричное отношение там, где в тексте «считает». Два понятия с общей частью — признак того, что ни одно не родовое.
+
+> «Наличие двух понятий, имеющих общую часть, указывает на то, что каждое из них не является родовым… если вместо родового отношения используется видовое, то исследователи теряют другие виды» — Т1 §1.2.18.
+
+**Не удваивать сущности.** Выводимое не вводится как исходное: производное — `D#`/`F#`/`P#`, а не новое `S#`. Неопределяемые понятия равноуровневы: ни одно не выражается через другие.
+
+> «Если мы вводим то, что выводимо, повторно, как исходное понятие, то это и будет удвоение сущности… надо гарантировать (или стремиться к тому), чтобы эти абстракции были одного уровня» — Т1 §1.2.12.
+
+**Альтернативные гипотезы основного отношения.** Для основного отношения рассматриваются 2–3 варианта (единичное / множественное / оба; читатель × экземпляр или читатель × издание; кортеж или сущность с отношениями). Варианты сравниваются по выразительной силе: «избыточно» или «недостаточно» для требований. Выбор записывается в журнал решений.
+
+> «Постулируя одно из двух или оба отношения, мы либо делаем теорию избыточной (выразительных средств гораздо больше, чем нужно), либо недостаточной» — Т2 §4.2.1.5.1.
+
+**Свойства отношения как решения.** Для каждой родовой структуры проходится стандартный перечень:
+
+| Свойство                            | Пример аксиомы                         |
+| :---------------------------------- | :------------------------------------- |
+| рефлексивность / антирефлексивность | `∀ξ∈X1 (ξ,ξ)∉S1`                       |
+| симметричность / асимметричность    | `∀(α,β)∈S1 (β,α)∉S1`                   |
+| транзитивность; ацикличность        | через замыкание `R{}`: `∀ξ∈X1 ξ∉F2[ξ]` |
+| однозначность (функциональность)    | `card(S1)=card(Pr1(S1))`               |
+| всюду определённость                | `Pr1(S1)=X1`                           |
+| несовместимость с другой структурой | `S1∩S2=∅`                              |
+
+Свойства не переносятся по привычке: «Аксиомы логически вытекают из ограничения предметной области» (Т2 §4.2.1.5.3). В разборе подчинения книга не запрещает ни симметричность, ни циклы — подчинение многоаспектно, и главнокомандующий может быть подчинён генштабу, которым руководит. По каждому свойству — решение с обоснованием. **Отсутствие аксиомы — тоже решение** и записывается в журнал (`choice: "без аксиомы"`). Спорные свойства выносятся на раунд 2 вопросов.
+
+> «…мы не вводим аксиому, требующую, чтобы отношение было определено на всем множестве людей. На этом примере подчеркнем, что отсутствие аксиом – тоже решение, т.к. это соответствует содержанию» — Т2 §4.2.1.5.3.
+
+**Проверка выразительных возможностей ядра** — до экспликации. Для каждого требования одна строка: как оно выразится через ядро (поле `via`: «`Pr2` выдач», «дополнение к E1 в `X2`», «замыкание блокировок»). Не выражается — меняется гипотеза ядра, а не формула. Это дешёвый гейт против непокрытого запроса.
+
+> «Составляется список понятий, которые мы хотим выразить, но уже в понятиях теории, введенных на предыдущих этапах… это отношение не дает понятия “коллективного руководства”. Следовательно, можно сделать вывод, что этот вариант отношений предметную область не отражает» — Т2 §4.2.1.7. Отсюда смена гипотезы: от единичного отношения к множественному.
+
+**Ограниченное исследование.** Термы первого ранга от ядра (проекции, дополнения вида `X1\Pr1(S1)`, пересечения однотипных структур) полезно перечислить и показать пользователю как «разнообразие» — источник вопросов раунда 2. В схему целиком они не добавляются.
+
+**Размер микротеории:** 3–6 отношений и 2–4 уровня конкретизации. Если требований больше, схема делится на микротеории, которые собираются синтезом (ОСС).
+
+> «Получающиеся при этом концептуальные схемы содержат, как правило, до 3–6 отношений (“элементарных теорий”) и 2–4 уровня конкретизации. Такие схемы мы относим к классу “микротеорий”» — Т1, предисловие.
+
+Гейт: каждое требование имеет `via`; решения по основному отношению и свойствам записаны; раунд 2 пройден; размер в пределах микротеории или есть план синтеза.
+
+### Этап 3. Экспликация
+
+Развёртывание **от требований**: выводятся только нужные понятия и их поставщики, через раскрытие структуры (`Pr`, `red`) и обособление (`F#`/`P#` для выражений со свободными переменными) — см. `CONTEXT.md`. Формально-дедуктивное развёртывание всех термов по рангам не нужно: число термов растёт комбинаторно.
+
+Правила проектирования формул — [CONCEPTUAL-SCHEMA.md](CONCEPTUAL-SCHEMA.md); синтаксис — [SYNTAX.md](SYNTAX.md); диагностики — [DIAGNOSTICS.md](DIAGNOSTICS.md).
+
+**Смысл важнее «зелёного».** Исправление диагностики не меняет смысл. Нельзя ради чистых диагностик:
+
+- удалять или ослаблять аксиому, связанную с инвариантом брифа, без нового решения в журнале;
+- превращать производное понятие (`D#`/`F#`/`P#`) в `S#`, `X#` или `C#`;
+- заменять формулу тривиальной (`∅`, голая ссылка `D5 := X1`, тавтология);
+- удалять конституенту, на которую ссылается бриф, или оставлять непустой `failed` после `best_effort`;
+- оставлять пустую конвенцию у неопределяемого понятия.
+
+Если смысл не удаётся выразить — вернись к ядру (другая гипотеза, промежуточные `D#`/`F#`) и запиши решение. Если ЯРЭ этого не выражает — запиши `openQuestions` и честно скажи «готово частично».
+
+Гейт: диагностики чисты; ни одно требование не ослаблено; `failed` пуст.
+
+### Этап 4. Интерпретация
+
+Сценарии брифа (`scenarios`) — маленькие интерпретации с ожиданиями: примеры и контрпримеры. Пишутся **в бриф до формул** (этап 1–2) и прогоняются на КМ непрерывно. Значения задаются подписями элементов. Ориентир — приёмочные тесты.
+
+- У каждого инварианта — позитивный (аксиома истинна) и негативный (ложна) сценарий.
+- У каждого различения — сценарий-свидетель, на котором значения понятий различаются.
+- При развитии схемы старые сценарии — регрессия.
+
+**Гипотетико-дедуктивный цикл:** гипотеза → вывод → интерпретация → пересмотр гипотезы. Провалился сценарий — сначала спроси, верна ли гипотеза ядра, и только потом правь формулу. Подгонка формулы под сценарий без пересмотра смысла — то же «озеленение».
+
+> «Затем производные понятия переносятся в предметную область, интерпретируются и на основе сравнения пересматриваются исходные предположения. Цикл “гипотеза-дедукция-интерпретация” замыкается» — Т1 §1.2.8.
+
+Гейт: все сценарии проходят; у каждого инварианта есть позитив и негатив; каждое различение подтверждено.
+
+### Этап 5. Ревью и сдача
+
+Ревью в два прохода: сначала **соответствие брифу** (требования, различения, инварианты, невыразимое, решения), затем форма ЯРЭ. Отчёт начинается с таблицы «требование → конституента → доказательство (сценарий)».
+
+**Когда КС закончена.** Когда выведенными понятиями объясняется всё зафиксированное содержание. Если требование не покрыто, причина — одна из трёх: утеряна абстракция (не хватает исходного понятия), понятие не выведено, или не реализована комбинация синтеза (нужна другая микротеория). Отчёт называет причину и следующий шаг.
+
+> «Если же остались какие-то необъяснимые части содержания, то можно предположить, что: – либо одна из абстракций утеряна, – либо она еще не выражена в имеющейся теории, – либо имеется нереализованная комбинация синтеза» — Т1 §1.2.18.
+
+## Синтез микротеорий
+
+Сложная предметная область — несколько микротеорий, объединённых синтезом через таблицу отождествлений ([DOMAIN.md](DOMAIN.md) «Синтез», [PORTAL-OSS.md](PORTAL-OSS.md)).
+
+Правила отождествления: исходное с исходным — можно; исходное одной схемы с производным другой — можно, при этом понятие становится конкретнее; производное с производным — только при полном совпадении структуры. Синтетическая аксиома связывает понятия разных микротеорий (пример: «прямой родственник не может быть в прямом подчинении»).
+
+**Бриф синтеза.** У каждой схемы ОСС свой бриф; брифы аргументов в результат не переносятся. Бриф результата описывает то, что даёт сам синтез: отождествления и новые отношения (решения), новые выводимые понятия (требования), синтетические аксиомы (инварианты). Синтез без нового — лишний.
+
+**Имена после синтеза.** Встроенные конституенты получают новые номера (rstool — следующие свободные по типу; синтез в ОСС на Portal перенумеровывает все имена подряд). Формулы, типизация и ссылки в терминах и текстовых определениях перенумеровываются автоматически, конвенции — нет. Поэтому в конвенциях только предметный смысл: без имён конституент и без номеров решений брифа.
+
+> «Не запрещено отождествлять производное понятие одной теории с исходным понятием другой… уровень абстракции этого понятия повышается… Запрещается отождествлять производные понятия с производными, за исключением очень незначительного числа совпадений, которые заключаются в полном совпадении структуры понятий» — Т1 §1.2.18.
+
+## Современные ориентиры
+
+Для агента, не для текста пользователю: требования к выразительным средствам ≈ competency questions; сценарии ≈ приёмочные тесты; расчистка ≈ разметка требований; микротеория ≈ модуль онтологии; синтез ≈ слияние онтологий с таблицей соответствий; журнал решений ≈ ADR.
+
+## Учебные примеры
+
+| Пример                                                                  | Что показывает                                                               |
+| :---------------------------------------------------------------------- | :--------------------------------------------------------------------------- |
+| [`examples/subordination/`](../examples/subordination/)                 | этапы 1–2 целиком: ограничения, альтернативы, свойства как решения           |
+| [`examples/kinship/`](../examples/kinship/)                             | родовое отношение «быть ребёнком» и выведенное разнообразие; бриф «обучение» |
+| [`examples/kinship-subordination/`](../examples/kinship-subordination/) | синтез двух микротеорий и синтетическая аксиома                              |

package/docs/MODEL-TESTING.md

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