@rsconcept/rstool 1.9.0 → 2.0.0

package/README.md

@@ -2,11 +2,11 @@
 
 Agent-facing library for **incremental RSForm construction**, **RSLang expression analysis**, **diagnostics**, **modeling**, and **evaluation**. It wraps [`@rsconcept/domain`](https://www.npmjs.com/package/@rsconcept/domain) with a deterministic session contract and a stdio JSON wrapper for LLM agents. MCP hosts can use it through [`@rsconcept/rstool-mcp`](https://www.npmjs.com/package/@rsconcept/rstool-mcp).
 
-**Contract version:** `3.3.0` — see [skills/rstool-helper/REFERENCE.md](./skills/rstool-helper/REFERENCE.md) for the full v3 API.
+**Contract version:** `3.3.0` — see [skills/rstool-runtime/REFERENCE.md](./skills/rstool-runtime/REFERENCE.md) for the full v3 API.
 
 ## Agent skill
 
-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.
+Agents build conceptual schemas that answer the user's request, not just pass the analyzer. The router skill `skills/rstool/` picks the scenario and names the stage skills (`skills/rs-scope`, `rs-core`, `rs-explicate`, `rs-interpret`, `rs-review`, `rs-synthesis`, `rs-explain`, `rs-portal`, `rstool-runtime`). The method is in `docs/METHOD.md`; a schema brief (`docs/BRIEF.md`) holds the expressiveness requirements, decisions and labelled scenarios, checked by `skills/scripts/check-brief.ts`. Only a **stub** of the router is installed into the project; see [Installing the agent skill](#installing-the-agent-skill) below.
 
 ## Install
 
@@ -26,7 +26,7 @@ The agent should read and follow:
 
 `node_modules/@rsconcept/rstool/skills/INSTALL.md`
 
-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.
+The procedure is agent-neutral: the agent adds a routing line to the project `AGENTS.md` (or the instructions file its host loads) and, if its host loads a project skills folder, a stub `rstool/SKILL.md` there (name, description and a path into `node_modules`; `npx rstool-skills install --dir <skills-dir>`). The skills and `docs/*.md` stay in the package and are read from `node_modules` when needed, so nothing is re-copied after an update.
 
 Details: `skills/README.md`.
 

package/dist/mappers/model-adapter.d.ts

@@ -5,7 +5,7 @@ import "../models/index.js";
 import { CstType } from "@rsconcept/domain/library/rsform";
 import { RSEngine } from "@rsconcept/domain/library/rsengine";
 //#region src/mappers/model-adapter.d.ts
-declare class ModelAdapter {
+export declare class ModelAdapter {
   setConstituentaValue(session: SessionState, input: SetConstituentaValueInput): Promise<SessionModelState>;
   setConstituentaValues(session: SessionState, input: {
     items: SetConstituentaValueInput[];
@@ -23,5 +23,4 @@ declare class ModelAdapter {
   private validateSetInput;
 }
 //#endregion
-export { ModelAdapter };
 //# sourceMappingURL=model-adapter.d.ts.map

package/dist/mappers/schema-adapter.d.ts

@@ -6,7 +6,7 @@ import "../models/index.js";
 import { RSForm } from "@rsconcept/domain/library/rsform";
 import { RSLangAnalyzer } from "@rsconcept/domain/rslang";
 //#region src/mappers/schema-adapter.d.ts
-declare class SchemaAdapter {
+export declare class SchemaAdapter {
   analyzeAgainstSession(session: SessionState, draft: ConstituentaDraft): {
     result: AnalysisResult;
     diagnostics: Diagnostic[];
@@ -20,5 +20,4 @@ declare class SchemaAdapter {
   private toAnalysisSchema;
 }
 //#endregion
-export { SchemaAdapter };
 //# sourceMappingURL=schema-adapter.d.ts.map

package/dist/mappers/types.d.ts

@@ -4,7 +4,7 @@ import "../models/index.js";
 import { RSErrorDescription, ValueClass } from "@rsconcept/domain/rslang";
 //#region src/mappers/types.d.ts
 /** Minimal domain error shape before mapping to {@link Diagnostic}. */
-interface DomainErrorLike {
+export interface DomainErrorLike {
   code: number;
   from: number;
   to: number;
@@ -12,16 +12,15 @@ interface DomainErrorLike {
   stack?: RSErrorDescription['stack'];
 }
 /** Minimal domain analysis shape before mapping to {@link AnalysisResult}. */
-interface DomainAnalysisLike {
+export interface DomainAnalysisLike {
   success: boolean;
   type: Record<string, unknown> | null;
   valueClass: ValueClass | null;
   errors: DomainErrorLike[];
 }
 /** Map a domain parser/semantic error to the public diagnostic shape. */
-declare function toDiagnostic(error: DomainErrorLike, expression: string, target?: DiagnosticTarget): Diagnostic;
+export declare function toDiagnostic(error: DomainErrorLike, expression: string, target?: DiagnosticTarget): Diagnostic;
 /** Map a domain analysis result to the public {@link AnalysisResult} shape. */
-declare function toPublicAnalysis(analysis: DomainAnalysisLike, expression: string, target?: DiagnosticTarget): AnalysisResult;
+export declare function toPublicAnalysis(analysis: DomainAnalysisLike, expression: string, target?: DiagnosticTarget): AnalysisResult;
 //#endregion
-export { DomainAnalysisLike, DomainErrorLike, toDiagnostic, toPublicAnalysis };
 //# sourceMappingURL=types.d.ts.map

package/dist/models/rstool-agent.js

@@ -1,2 +1 @@
-import { t as RSToolAgent } from "../models-D06g8LId.js";
-export { RSToolAgent };
+export { t as RSToolAgent } from "../models-D06g8LId.js";

package/dist/session/session-store.d.ts

@@ -2,14 +2,14 @@ import { a as Diagnostic, r as ListDiagnosticsFilters } from "../diagnostic-CtxX
 import { n as SessionRevision, r as SessionState, t as SessionHandle } from "../session-OaLqLq0H.js";
 import "../models/index.js";
 //#region src/session/session-store.d.ts
-interface SessionStoreOptions {
+export interface SessionStoreOptions {
   persistenceDir?: string;
 }
 interface SessionEnvelope {
   state: SessionState;
   diagnostics: Diagnostic[];
 }
-declare class SessionStore {
+export declare class SessionStore {
   private sessions;
   private readonly persistence;
   constructor(options?: SessionStoreOptions);
@@ -30,5 +30,5 @@ declare class SessionStore {
   private persist;
 }
 //#endregion
-export { SessionStore, SessionStoreOptions };
+export {};
 //# sourceMappingURL=session-store.d.ts.map

package/dist/session/session-store.js

@@ -1,2 +1 @@
-import { n as SessionStore } from "../models-D06g8LId.js";
-export { SessionStore };
+export { n as SessionStore } from "../models-D06g8LId.js";

package/dist/wrapper/client.d.ts

@@ -1,6 +1,6 @@
 //#region src/wrapper/client.d.ts
 /** One JSON line emitted by the stdio wrapper (request response or ready event). */
-interface WrapperResponse<T = unknown> {
+export interface WrapperResponse<T = unknown> {
   id: string | number | null;
   ok: boolean;
   result?: T;
@@ -11,7 +11,7 @@ interface WrapperResponse<T = unknown> {
   };
 }
 /** Options for spawning the `rstool-wrapper` child process. */
-interface RSToolWrapperClientOptions {
+export interface RSToolWrapperClientOptions {
   /** Executable to spawn. Default: `npm`. Passed as argv, not a shell string. */
   command?: string;
   /** Arguments passed to `command`. Default: `['run', 'wrapper']`. */
@@ -24,7 +24,7 @@ interface RSToolWrapperClientOptions {
  *
  * Sends one JSON request per line on stdin and reads one JSON response per line from stdout.
  */
-declare class RSToolWrapperClient {
+export declare class RSToolWrapperClient {
   private process;
   private input;
   private pending;
@@ -58,5 +58,4 @@ declare class RSToolWrapperClient {
   private handleLine;
 }
 //#endregion
-export { RSToolWrapperClient, RSToolWrapperClientOptions, WrapperResponse };
 //# sourceMappingURL=client.d.ts.map

package/docs/BRIEF.md

@@ -0,0 +1,93 @@
+# Бриф схемы
+
+Бриф — постановка задачи концептуализации, журнал решений и исполнимые сценарии в одном JSON. Метод, который за ним стоит, — [METHOD.md](METHOD.md). JSON-схема — [brief.schema.json](brief.schema.json).
+
+Пока бриф хранится файлом `brief.json` в папке задачи, рядом с сессией (не в пакете rstool). Проверка схемы по брифу — скрипт `skills/scripts/check-brief.ts` (см. «Проверка»). В rstool 4.0 бриф переедет в сессию, а на Portal — в блок «Задание» паспорта схемы.
+
+## Поля
+
+| Поле             | Этап   | Что записать                                                                                                                                                        |
+| :--------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `status`         | 1      | `draft` — составляется; `confirmed` — пользователь подтвердил; `assumed` — спросить нельзя, ответы в `assumptions`                                                  |
+| `approach`       | 1      | `research` — экспликация; `education` — обучение; `project` — основа для ПО / ОСС                                                                                   |
+| `object`, `task` | 1      | объект исследования; задача и точка зрения — по одной-две фразы                                                                                                     |
+| `source`         | 1      | документ и разделы, ссылка на схему Portal                                                                                                                          |
+| `restrictions`   | 1      | что исключено (`excludes`) и что из-за этого невыразимо (`inexpressible`)                                                                                           |
+| `expressiveness` | 1–3    | требования к выразительным средствам: `concept`, `ref` в источнике; `via` (этап 2) — как выразится через ядро; `constituent` (этап 3) — имя конституенты или `null` |
+| `distinctions`   | 1, 4   | пары `between` (id требований `E#` или имена конституент) и `witness` — сценарий, где они различаются                                                               |
+| `invariants`     | 1, 3–4 | правило `text`, аксиома `constituent`, сценарии `positive` и `negative`                                                                                             |
+| `decisions`      | 2–3    | журнал: `topic`, `alternatives`, `choice`, `rationale`; `supersedes` — какое решение отменено                                                                       |
+| `scenarios`      | 1–4    | маленькие интерпретации с ожиданиями (ниже)                                                                                                                         |
+| `questions`      | 1–2    | вопросы раундов 1–2: `text`, `proposed`, `consequence`, `answer`                                                                                                    |
+| `assumptions`    | 1–2    | то, что не спросили или не смогли спросить                                                                                                                          |
+| `openQuestions`  | любой  | что осталось нерешённым, в том числе то, что ЯРЭ не выражает                                                                                                        |
+
+Идентификаторы: `L#` ограничения, `E#` требования, `V#` различения, `I#` инварианты, `DC#` решения, `SC#` сценарии. Идентификатор не переиспользуется после удаления.
+
+Ссылки на конституенты — по имени (`D3`). При перенумерации (`restoreOrder`, синтез) обнови ссылки. Брифы аргументов синтеза в результат не переносятся: у синтезированной схемы свой бриф по итоговым именам (`skills/rs-synthesis`). Конвенции и текстовые определения не ссылаются на `DC#`: бриф не уходит вместе со схемой.
+
+## Сценарии
+
+```json
+{
+  "id": "SC2",
+  "title": "Двойная выдача e1",
+  "base": "SC1",
+  "values": {
+    "S1": [
+      ["ann", "e1", 3],
+      ["bob", "e1", 4]
+    ]
+  },
+  "expect": [
+    { "of": "A1", "holds": false },
+    { "of": "D2", "contains": ["e2"], "excludes": ["e1"] },
+    { "of": "F1", "args": ["ann"], "value": ["e1"] },
+    { "expr": "card(D1)", "value": 1 }
+  ]
+}
+```
+
+- `values` — значения неопределяемых понятий **подписями**: `X#` / `C#` — массив подписей элементов; `S#` — по типизации: множество — массив, кортеж — массив компонент, элементы `Z` — числа. Индексы и `TUPLE_ID` не нужны.
+- Понятия, не перечисленные в `values`, пусты. `base` наследует значения другого сценария; перечисленные здесь заменяют унаследованные целиком.
+- `expect` — ожидания:
+  - `of` — конституента: `D#` (значение), `A#` / `T#` (`holds`), `F#` / `P#` с `args` (аргументы подписями);
+  - `expr` — выражение ЯРЭ над схемой (`card(D1)`, `D2⊆D1` с `holds`);
+  - `value` — точное значение; `contains` / `excludes` — элементы, которые должны входить / не входить; `holds` — истинность.
+- Порядок элементов в множествах не важен.
+
+## Проверка
+
+Из корня пакета rstool (в workspace Portal — `rsconcept/rstool`, в npm-проекте — `node_modules/@rsconcept/rstool`):
+
+```bash
+npx tsx skills/scripts/check-brief.ts --session <abs>/session.json --brief <abs>/brief.json [--base <abs>/v1-session.json] [--json]
+```
+
+В workspace Portal: `pnpm --filter @rsconcept/rstool exec tsx skills/scripts/check-brief.ts …`. Сессия — файл `exportSession`. Сценарии выполняются на копии сессии; сама сессия не меняется.
+
+`--review` — режим ревью чужой схемы: блокеры — находки отчёта, следующий шаг — `rs-review`, а не правка.
+
+Скрипт печатает этап, покрытие, матрицу приёмки «сценарий × ожидание → факт», блокеры, предупреждения и следующий шаг. Код выхода `0` — блокеров нет, `1` — есть.
+
+| Проверка                                                                                                        | Блокер когда                                                                                 |
+| :-------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- |
+| статус брифа                                                                                                    | `draft`                                                                                      |
+| требование без `via`                                                                                            | всегда (этап 2 не пройден)                                                                   |
+| требование без конституенты                                                                                     | всегда; причина — не хватает исходного понятия, понятие не выведено или нужен синтез         |
+| инвариант без аксиомы                                                                                           | всегда                                                                                       |
+| инвариант без позитива / негатива                                                                               | `project`; иначе предупреждение                                                              |
+| сценарий не прошёл                                                                                              | всегда                                                                                       |
+| различение не подтверждено сценарием                                                                            | `research`; иначе предупреждение                                                             |
+| пустая конвенция `X#` / `C#` / `S#`                                                                             | всегда                                                                                       |
+| диагностики с `severity: error`                                                                                 | всегда                                                                                       |
+| «сироты» — вне путей к требованиям и аксиомам                                                                   | `project`; иначе предупреждение                                                              |
+| с `--base`: аксиома или конституента брифа удалена, производное стало неопределяемым, формула стала тривиальной | если имени нет в журнале решений                                                             |
+| требование выражено `S#` без решения                                                                            | предупреждение                                                                               |
+| описание схемы пусто; конвенции или текстовые определения ссылаются на `DC#`                                    | предупреждение: бриф не уходит ни в Portal, ни в результат синтеза — решения пишутся словами |
+
+Чистый вывод не доказывает смысл схемы: он показывает только то, что записано в брифе. Полнота брифа — ответственность этапов 1–2.
+
+## Лёгкий бриф
+
+Для точечной правки (одна формула, одно понятие) достаточно: `status`, `approach`, `object`, `task`, одно требование с `via` и `constituent` и один сценарий. Объяснение формулы и вопросы по синтаксису обходятся без брифа.

package/docs/CONCEPTUAL-SCHEMA.md

@@ -73,7 +73,21 @@ card(S1) = card(Pr1,2(S1))
 ```
 
 Это заменяет длинные `∀d1,d2∈S1 ...`.
-Оставляй `∀` / `∃`, только если выражение нельзя задать через множества, проекции, фильтры, `card`.
+Оставляй `∀` / `∃`, только если выражение нельзя задать через множества, проекции, фильтры, сравнение с `∅` или `card`.
+
+## Пустота и мощность
+
+(Не)пустота множества — сравнение с пустым множеством, не арифметика мощности.
+
+| Нужно                    | Пиши                    | Не пиши                         |
+| :----------------------- | :---------------------- | :------------------------------ |
+| непусто                  | `S ≠ ∅`                 | `card(S) > 0`, `card(S) ≥ 1`    |
+| пусто                    | `S = ∅`                 | `card(S) = 0`                   |
+| пересечение непусто      | `A ∩ B ≠ ∅`             | `card(A ∩ B) > 0`               |
+| ровно один элемент       | `card(S) = 1`           | —                               |
+| сравнение численностей   | `card(S1) = card(S2)`   | —                               |
+
+`∅` в `=` / `≠` подстраивается под ступень сравниваемого множества. Не используй `∅` как нейтральный элемент операций (`X1 ∪ ∅` → `invalidEmptySetUsage`).
 
 ## Производные понятия
 
@@ -82,6 +96,7 @@ card(S1) = card(Pr1,2(S1))
 - `Prk(…)` / `Pri,j(…)`;
 - `Fi*k[{…}](…)`;
 - `D{ξ∈… | F[ξ] = …}`;
+- `S ≠ ∅` / `A ∩ B ≠ ∅`;
 - `card(F[ξ]) = 1`.
 
 Перед `D{x∈… | ∃d1∈… ∃d2∈…}` проверь, нельзя ли взять `Pr` от уже введенного отношения.

package/docs/CONSTRUCTIONS.md

@@ -355,13 +355,25 @@ Pr2(Fi1[{ξ}](S1))
 
 **Антипаттерн.** `red` по множеству, элементы которого не множества (`invalidReduce`).
 
+### Пустое множество (`∅`)
+
+**Запись.** `∅`. Сравнение: `S = ∅`, `S ≠ ∅`.
+
+**Что считается.** Пустое множество. В равенстве и неравенстве типизация `ℬ(R0)` подстраивается под сравниваемое множество.
+
+**Как сказать.** «S пусто» / «S непусто».
+
+**Пример.** `F1[a] ∩ F1[b] ≠ ∅` — пересечение непусто.
+
+**Антипаттерн.** `card(S) > 0` или `card(S) = 0` вместо сравнения с `∅`. `X1 ∪ ∅` — бессмысленная операция (`invalidEmptySetUsage`).
+
 ### Мощность (`card`)
 
 **Как сказать.** «сколько элементов в конечном множестве S» (мощность `card(S)`). Результат — целое (`Z`).
 
-**Пример.** `card(X1) > 5` — логическое сравнение мощности.
+**Пример.** `card(X1) > 5` — логическое сравнение мощности. `card(S) = 1` — ровно один элемент.
 
-**Не сосед.** `card` не заменяет [квантор](#кванторы) «для всех». Арифметика `+` `-` `*` и порядок `<` только на `Z` или `C#`, не на элементах `X#` ([BASE-SELECTION.md](BASE-SELECTION.md)).
+**Не сосед.** (Не)пустота — карточка «Пустое множество» выше. `card` не заменяет [квантор](#кванторы) «для всех». Арифметика `+` `-` `*` и порядок `<` только на `Z` или `C#`, не на элементах `X#` ([BASE-SELECTION.md](BASE-SELECTION.md)).
 
 ## Ссылка на справку Portal
 

package/docs/DIAGNOSTICS.md

@@ -178,6 +178,7 @@ runtime-ошибки в теле `F#`/`P#`) диагностика несёт `s
 | `0x8808` | `invalidCard`                      | `[arg]`                            | `card(arg)` только над множеством.                                                                                                                                                                                               |
 | `0x8809` | `invalidDebool`                    | `[arg]`                            | `debool(arg)` требует ступень-множество с гарантией синглетона.                                                                                                                                                                  |
 | `0x880B` | `globalFuncWithoutArgs`            | `[name]`                           | Терм-/предикат-функция `name` вызвана без аргументов: нужен `F#[…]` / `P#[…]`.                                                                                                                                                   |
+| `0x880C` | `globalDeleted`                    | `[name]`                           | Ссылка на удаленную конституенту: при удалении в формулах зависимых конституент обозначение заменяется на `DEL`. Подставь действующее обозначение или перепиши формулу. Синтаксические ошибки в такой формуле не сообщаются.     |
 | `0x8830` | `projectionSetArgumentNotSet`      | `[operator, actual]`               | `Pr*` применяется к множеству; аргумент не типизирован как `ℬ(H)`.                                                                                                                                                               |
 | `0x8831` | `projectionSetArgumentNotTupleSet` | `[operator, actual]`               | `Pr*` требует множество кортежей `ℬ(H1×…×Hn)`; аргумент — множество не-кортежей, напр. `ℬ(X1)`.                                                                                                                                  |
 | `0x8832` | `projectionSetIndexOutOfRange`     | `[operator, index, arity, actual]` | Индекс проекции `index` превышает размерность `arity` кортежа аргумента `actual`.                                                                                                                                                |
@@ -186,7 +187,7 @@ runtime-ошибки в теле `F#`/`P#`) диагностика несёт `s
 | `0x8813` | `invalidEnumeration`               | `[a, b]`                           | Элементы перечисления разной типизации (`a` ≠ `b`).                                                                                                                                                                              |
 | `0x8814` | `invalidCortegeDeclare`            | —                                  | Число переменных кортежа ≠ размерности `×` (напр. `∀(a,b)∈X1`).                                                                                                                                                                  |
 | `0x8816` | `invalidElementPredicate`          | `[a, operator, c]`                 | `a operator c` (`ξ∈S`) с несовместимыми ступенями: `a` — тип элемента, `c` — тип множества.                                                                                                                                      |
-| `0x8817` | `invalidEmptySetUsage`             | —                                  | Бессмысленное использование `∅` (напр. `X1∪∅`).                                                                                                                                                                                  |
+| `0x8817` | `invalidEmptySetUsage`             | —                                  | Бессмысленное использование `∅` как нейтрального элемента операций (напр. `X1∪∅`). Сравнение `S=∅` / `S≠∅` допустимо.                                                                                                            |
 | `0x8818` | `invalidArgsArity`                 | `[expected, actual]`               | Неверное число аргументов функции (`expected` ≠ `actual`).                                                                                                                                                                       |
 | `0x8819` | `invalidArgumentType`              | `[expected, actual]`               | Тип аргумента не соответствует объявлению: ожидалось `expected`, получено `actual`.                                                                                                                                              |
 | `0x881C` | `globalStructure`                  | —                                  | Некорректный домен родовой структуры (`cstType` STRUCTURED): нужна ступень-структура вроде `ℬ(X1×D2)`, а не, напр., `X1∩X1`.                                                                                                     |
@@ -233,4 +234,4 @@ runtime-ошибки в теле `F#`/`P#`) диагностика несёт `s
 
 ## Цикл исправления
 
-Пошаговый цикл — в `../skills/rstool-helper/GUIDE.md`, раздел «Цикл диагностик». Здесь — справочник кодов.
+Пошаговый цикл — в `../skills/rs-explicate/SKILL.md`, раздел «Цикл диагностик». Здесь — справочник кодов.

package/docs/DOMAIN.md

@@ -22,6 +22,18 @@
 - **Интерпретация** — соотнесение понятий КС с сущностями предметной области. В концептуальной модели задаётся значениями неопределяемых конституент и вычислением производных.
 - **Биективная переносимость** — независимость значения формального определения от биективной замены интерпретаций неопределяемых понятий. Для `X#` опирается на несравнимость элементов; анализатор ЯРЭ отсекает формулы, нарушающие переносимость.
 
+## Термины метода
+
+Процесс концептуализации — [METHOD.md](METHOD.md); бриф — [BRIEF.md](BRIEF.md).
+
+- **Требования к выразительным средствам** — понятия, которые КС обязана выразить: то, ради чего её строят. В брифе — `expressiveness`.
+- **Ограничения предметной области** — что сознательно исключено из рассмотрения (время, история, процедуры…) вместе с перечнем понятий, которые из-за этого **невыразимы**. В брифе — `restrictions`.
+- **Различение** — пара понятий, которые схема должна развести, хотя в источнике они смешаны или легко склеиваются.
+- **Журнал решений** — записанные решения о ядре: альтернативы, выбор, обоснование; отсутствие аксиомы — тоже решение. Изменить решение можно только новым решением (`supersedes`).
+- **Сценарий** — маленькая интерпретация неопределяемых понятий подписями элементов с ожидаемыми значениями производных понятий и истинностью аксиом: пример или контрпример.
+- **Микротеория** — небольшая КС одного аспекта (3–6 отношений, 2–4 уровня конкретизации); сложная предметная область собирается из микротеорий синтезом.
+- **Ранг терма** — глубина терма в графе термов от ядра: термы первого ранга строятся непосредственно из неопределяемых понятий.
+
 ## Конституенты
 
 **Конституента** — часть КС. Поля и правила валидации см. в [CONSTITUENTA.md](CONSTITUENTA.md); здесь только предметные роли.

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/) | синтез двух микротеорий и синтетическая аксиома                              |