@rsconcept/rstool 1.4.3 → 1.6.0

package/skills/rstool-helper/REFERENCE.md

@@ -1,34 +1,68 @@
 # ЯРЭ и rstool — справочник
 
+Контракт library / stdio / MCP для агентов. Воркфлоу — [GUIDE.md](GUIDE.md). Примеры — [EXAMPLES.md](EXAMPLES.md). Язык — `docs/*.md`.
+
 ## Контракт rstool
 
 - Пакет: `@rsconcept/rstool`
-- Версия контракта: `3.0.0` (`CONTRACT_VERSION`)
+- Версия контракта: `3.1.0` (`CONTRACT_VERSION`)
 - Основной класс: `RSToolAgent`
 - Публичные импорты: `@rsconcept/rstool` и `@rsconcept/rstool/wrapper`
+- Опции: `new RSToolAgent({ persistenceDir? })` — каталог для сохранения сессий между перезапусками (stdio/MCP: `RSTOOL_PERSISTENCE_DIR`)
+
+Почти все методы принимают optional `sessionId` вторым аргументом (в stdio/MCP — поле `sessionId` в плоских `params`). Без него используется текущая сессия; при необходимости сессия создаётся лениво.
 
 ### Методы library API
 
-| Метод                                          | Назначение                                                         |
-| ---------------------------------------------- | ------------------------------------------------------------------ |
-| `ensureSession(initial?)`                      | Вернуть текущую сессию или создать новую                           |
-| `createSession(initial?)`                      | Новая in-memory сессия                                             |
-| `getCurrentSession()`                          | Текущая активная сессия или `null`                                 |
-| `setCurrentSession(sessionId)`                 | Сделать сессию текущей                                             |
-| `applySchemaPatch(input, sessionId?)`          | Единственный путь правки схемы                                     |
-| `getSessionState(detail?, sessionId?)`         | `summary` (default) или `full`                                     |
-| `listDiagnostics(filters?, sessionId?)`        | Активные диагностики (`kind`: `expression` \| `schema` \| `model`) |
-| `analyzeExpression(input, sessionId?)`         | Разбор без сохранения (`recordDiagnostics?`)                       |
-| `commitStep(message?, sessionId?)`             | Ревизия                                                            |
-| `exportSession(sessionId?)`                    | JSON сессии                                                        |
-| `exportPortal({ kind, format? }, sessionId?)`  | Portal Load from JSON                                              |
-| `importData(payload, kind?)`                   | Импорт сессии / Portal (`kind` см. ниже)                           |
-| `setModelValues({ set?, clear? }, sessionId?)` | Значения модели (async — нужен `await`)                            |
-| `getModelState(sessionId?)`                    | Состояние интерпретации                                            |
-| `evaluate(input, sessionId?)`                  | Scratch или конституента                                           |
-| `recalculateModel(sessionId?)`                 | Пересчёт                                                           |
-
-### `applySchemaPatch`
+| Метод                                          | Назначение                                  |
+| ---------------------------------------------- | ------------------------------------------- |
+| `ensureSession(initial?)`                      | Вернуть текущую сессию или создать новую    |
+| `createSession(initial?)`                      | Новая in-memory сессия (становится текущей) |
+| `getCurrentSession()`                          | Текущая активная сессия или `null`          |
+| `setCurrentSession(sessionId)`                 | Сделать сессию текущей                      |
+| `applySchemaPatch(input, sessionId?)`          | Единственный путь правки схемы              |
+| `getSessionState(detail?, sessionId?)`         | `summary` (default) или `full`              |
+| `listDiagnostics(filters?, sessionId?)`        | Активные диагностики                        |
+| `analyzeExpression(input, sessionId?)`         | Разбор без сохранения                       |
+| `commitStep(message?, sessionId?)`             | Ревизия                                     |
+| `exportSession(sessionId?)`                    | JSON-строка сессии                          |
+| `exportPortal({ kind, format? }, sessionId?)`  | Portal Load from JSON                       |
+| `importData(payload, kind?)`                   | Импорт сессии / Portal                      |
+| `setModelValues({ set?, clear? }, sessionId?)` | Значения модели (**async** — `await`)       |
+| `getModelState(sessionId?)`                    | Состояние интерпретации                     |
+| `evaluate(input, sessionId?)`                  | Scratch или конституента                    |
+| `recalculateModel(sessionId?)`                 | Пересчёт производных                        |
+| `restoreOrder(sessionId?)`                     | Упорядочить конституенты (топология + семантика) |
+
+Служебные (stdio / MCP): `ping` / `pong`+`contractVersion`; `methods` / `list_methods`.
+
+### Library ↔ stdio ↔ MCP
+
+Stdio использует **camelCase** имён методов (как library). MCP (`@rsconcept/rstool-mcp`) — **snake_case**. Params везде **плоские** (без обёртки `input`).
+
+| Library / stdio     | MCP tool              |
+| ------------------- | --------------------- |
+| `ping`              | `ping`                |
+| `methods`           | `list_methods`        |
+| `ensureSession`     | `ensure_session`      |
+| `createSession`     | `create_session`      |
+| `getCurrentSession` | `get_current_session` |
+| `setCurrentSession` | `set_current_session` |
+| `applySchemaPatch`  | `apply_schema_patch`  |
+| `getSessionState`   | `get_session_state`   |
+| `listDiagnostics`   | `list_diagnostics`    |
+| `analyzeExpression` | `analyze_expression`  |
+| `commitStep`        | `commit_step`         |
+| `exportSession`     | `export_session`      |
+| `exportPortal`      | `export_portal`       |
+| `importData`        | `import_data`         |
+| `setModelValues`    | `set_model_values`    |
+| `getModelState`     | `get_model_state`     |
+| `evaluate`          | `evaluate`            |
+| `recalculateModel`  | `recalculate_model`   |
+| `restoreOrder`      | `restore_order`       |
+
+## `applySchemaPatch`
 
 ```ts
 tool.applySchemaPatch({
@@ -38,23 +72,132 @@ tool.applySchemaPatch({
 });
 ```
 
-- `items` упорядочиваются автоматически: поставщики раньше потребителей.
-- `id` и `cstType` можно опускать — выводятся из префикса `alias` (`X/C/S/D/F/P/A/T/N`).
-- `mode`: `'atomic'` (default; откат всей пачки при первой ошибке) или `'best_effort'` (применяются корректные элементы).
-- `commitMessage` фиксирует ревизию после успешного patch.
+**Вход**
+
+| Поле             | Смысл                                                                                                        |
+| ---------------- | ------------------------------------------------------------------------------------------------------------ |
+| `items`          | Массив патчей; у каждого обязателен `alias`                                                                  |
+| `initial?`       | `alias` / `title` / `comment` — только если для patch создаётся новая сессия                                 |
+| `mode?`          | `'atomic'` (default) — откат всей пачки при первой ошибке; `'best_effort'` — применяются корректные элементы |
+| `commitMessage?` | После успешного patch фиксирует ревизию                                                                      |
+
+**Патч элемента:** `alias` обязателен; `id`, `cstType`, `definitionFormal`, `term`, `definitionText`, `convention` опциональны. `id` и `cstType` выводятся из префикса `alias` (`X/C/S/D/F/P/A/T/N`). Поля мержатся с существующей конституентой.
+
+**Поведение:** `items` упорядочиваются автоматически (поставщики раньше потребителей).
+
+**Результат:** `{ success, applied, failed, diagnostics, session, summary, revision? }`.
+
+- `applied` — успешно применённые конституенты со `analysis`.
+- `failed` — `{ draft, diagnostics }[]` (при `best_effort` или атомарном отказе).
+- `summary` — компактный обзор сессии (см. ниже).
+- `revision` — если был `commitMessage`.
+
+Для крупных импортов с частичными ошибками формул предпочитай `mode: 'best_effort'`, затем правь оставшееся по `failed` / `listDiagnostics`.
+
+## `getSessionState`
+
+- `getSessionState()` / `getSessionState('summary')` → `SessionSummary`:
+  - `sessionId`, `contractVersion`, `alias`, `title`, `comment`
+  - `itemCount`, `modelItemCount`, `diagnosticsCount`
+  - `items[]`: `{ id, alias, cstType, analysisSuccess }`
+  - `diagnostics[]` (активные)
+  - `lastRevision?`
+- `getSessionState('full')` → полный `SessionState` (все конституенты с формулами, модель, ревизии). Для обзора агенту обычно хватает `summary`.
+
+## `listDiagnostics`
+
+```ts
+tool.listDiagnostics();
+tool.listDiagnostics({ kind: 'expression' });
+tool.listDiagnostics({ kind: 'schema', constituentId: 3, severity: 'error' });
+```
+
+Фильтры: `kind?: 'expression' | 'schema' | 'model'`, `constituentId?`, `severity?: 'error' | 'warning'`.
+
+Элемент диагностики (агентский вид): `kind`, `code`, `name`, `severity`, `alias?`, `expression`, `from`, `to`, `params?`. Ключ для поиска исправления — `name` ([DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md)).
+
+## `analyzeExpression`
+
+```ts
+tool.analyzeExpression({
+  expression: 'Pr1(S1)',
+  cstType: CstType.TERM,
+  recordDiagnostics: false // default
+});
+```
+
+**Вход:** `expression`, `cstType` (обязательны); `recordDiagnostics?` — писать ли диагностики в сессию (default `false`).
+
+**Результат:** `{ success, type, valueClass, diagnostics }`. Не сохраняет конституенту. Для черновика формулы — до `applySchemaPatch`.
+
+## `evaluate`
+
+Ровно один вариант входа:
+
+- конституента: `{ constituentId }`
+- scratch: `{ expression, cstType }`
+
+**Результат:** `{ success, value, status, iterations, cacheHits, diagnostics }`.
+
+`status` — статус вычисления КМ (`HAS_DATA`, `EMPTY`, `AXIOM_FALSE`, `EVAL_FAIL`, … — [DOMAIN.md](../../docs/DOMAIN.md)).
+
+## `setModelValues` / `getModelState` / `recalculateModel`
+
+```ts
+await tool.setModelValues({
+  set: [{ target: 1, value: { 0: 'a', 1: 'b' } }],
+  clear: [3]
+});
+```
+
+- `set[]`: `{ target, value, type? }` — `target` = id конституенты; `type` обычно не нужен.
+- `clear[]`: id для сброса значений.
+- Метод **async**. После изменения данных пересчитываются диагностики модели.
+- `getModelState()` → `{ items: [{ id, type, value }] }`.
+- `recalculateModel()` → `{ items: [{ id, alias, value, status }] }`.
+
+Формы `value` для `X#` / `S#` — [MODEL-TESTING.md](../../docs/MODEL-TESTING.md).
+
+## `restoreOrder`
+
+Упорядочивает конституенты сессии одним проходом Kahn:
+
+- формальные зависимости — жёстко (поставщик раньше зависимого);
+- семантические дети — сразу после родителя, если уже готовы;
+- иначе — стабильно относительно приоритета типов/ядра.
+
+```ts
+const { orderedAliases } = tool.restoreOrder();
+// → { orderedIds: number[], orderedAliases: string[] }
+```
+
+## `importData` / `exportSession` / `exportPortal`
 
 ### `importData(payload, kind?)`
 
-`kind`: `'auto'` (default; определяет формат по содержимому), `'session'`, `'portal-details'` (ответ `GET /api/rsforms/:id/details`), `'portal-schema'` (Portal Load from JSON). После импорта новая сессия становится текущей.
+`kind`: `'auto'` (default), `'session'`, `'portal-details'` (`GET /api/rsforms/:id/details`), `'portal-schema'` (Portal Load from JSON). После импорта новая сессия становится текущей. Возвращает `SessionHandle`.
 
-### Протокол stdio
+Portal JSON из `/details` **не** является `exportSession` — не передавай его с `kind: 'session'`.
 
-Плоские `params` (без `input`). Опционально: переменная окружения `RSTOOL_PERSISTENCE_DIR` — каталог для сохранения сессий между перезапусками обёртки (в library API — `new RSToolAgent({ persistenceDir })`).
+### `exportSession()`
 
-Служебные методы:
+JSON-строка сессии для последующего `importData(..., 'session')`.
 
-- `ping` — liveness и `contractVersion`.
-- `methods` — список доступных stdio-методов.
+### `exportPortal({ kind, format? })`
+
+- `kind`: `'schema'` | `'model'`
+- `format?`: `'json'` (default, строка) | `'object'`
+- Для загрузки в Portal UI: обычно `exportPortal({ kind: 'schema' })`.
+
+## `commitStep` / сессии
+
+- `commitStep(message?)` → `{ revisionId, at, message? }`.
+- `ensureSession` / `createSession` принимают optional `initial`: `alias`, `title`, `comment` (и прочие поля `SessionState` в library).
+- `SessionHandle`: `{ sessionId, contractVersion }`.
+
+## Протокол stdio
+
+Плоские `params`. Переменная окружения `RSTOOL_PERSISTENCE_DIR` — каталог персистентности.
 
 ```json
 {"id":"2","method":"applySchemaPatch","params":{"items":[{"alias":"X1"}]}}
@@ -62,8 +205,23 @@ tool.applySchemaPatch({
 {"id":"8","method":"evaluate","params":{"constituentId":3}}
 {"id":"9","method":"exportPortal","params":{"kind":"schema"}}
 {"id":"10","method":"importData","params":{"payload":"..."}}
+{"id":"11","method":"getSessionState","params":{"detail":"summary"}}
 ```
 
-## Документация
-
-Воркфлоу: `GUIDE.md`. Примеры: `EXAMPLES.md`. Язык: `docs/*.md`.
+## Help map: ошибка → документ
+
+| Ситуация                                           | Куда                                                    |
+| -------------------------------------------------- | ------------------------------------------------------- |
+| Код / `name` диагностики                           | [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md)             |
+| Синтаксис операторов, `D{}`/`I{}`/`R{}`, `F#`/`P#` | [SYNTAX.md](../../docs/SYNTAX.md)                       |
+| Ступени, `AnalysisResult.type`                     | [TYPIFICATION.md](../../docs/TYPIFICATION.md)           |
+| `X#` vs `C#` vs `Z`, переносимость                 | [BASE-SELECTION.md](../../docs/BASE-SELECTION.md)       |
+| Проектирование, `F#` vs пары, ревью                | [CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md) |
+| Поля и валидация конституенты                      | [CONSTITUENTA.md](../../docs/CONSTITUENTA.md)           |
+| Формы значений КМ, тесты                           | [MODEL-TESTING.md](../../docs/MODEL-TESTING.md)         |
+| Ссылка Portal, REST, curl                          | [PORTAL-API.md](../../docs/PORTAL-API.md)               |
+| Термины, статусы, «не путать»                      | [DOMAIN.md](../../docs/DOMAIN.md)                       |
+| Воркфлоу агента                                    | [GUIDE.md](GUIDE.md)                                    |
+| Сниппеты и антипаттерны                            | [EXAMPLES.md](EXAMPLES.md)                              |
+
+Исходники кодов ошибок ЯРЭ: `@rsconcept/domain` (`RSErrorCode`, `error.ts`). Не дублируй грамматику в skill — правь domain и при необходимости этот help map.

package/skills/rstool-helper/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rstool-helper
 description: >-
-  ЯРЭ (язык родоструктурной экспликации), формальные определения и проектирование концептуальных схем для агентов. Читай GUIDE и docs из node_modules.
+  ЯРЭ и концептуальные схемы через rstool: концептуализация, ревью/оценка КС,
+  правки и диагностики формул, проверка на КМ (evaluate), выбор X#/C#/Z,
+  импорт/экспорт Portal (/rsforms, /details). Читай GUIDE и docs из node_modules.
 ---
 
 # rstool-helper
@@ -16,15 +18,32 @@ description: >-
 
 Затем продолжай с каноническими файлами ниже.
 
-## Канонические файлы (читать перед работой с rstool)
+## Канонические файлы
 
-- **Начни здесь** — воркфлоу и чеклисты: `node_modules/@rsconcept/rstool/skills/rstool-helper/GUIDE.md`
-- API, stdio, контракт: `node_modules/@rsconcept/rstool/skills/rstool-helper/REFERENCE.md`
-- Примеры, типичные ошибки: `node_modules/@rsconcept/rstool/skills/rstool-helper/EXAMPLES.md`
-- Язык и предметная область: `node_modules/@rsconcept/rstool/docs/*.md`
-- Процедура установки: `node_modules/@rsconcept/rstool/skills/INSTALL.md`
+Префикс путей: `node_modules/@rsconcept/rstool/`.
 
-Перед началом задачи rstool всегда открывай **GUIDE.md**, затем по необходимости **REFERENCE.md** / **EXAMPLES.md** / нужные `docs/*.md`.
+| Что                                                 | Путь                                |
+| :-------------------------------------------------- | :---------------------------------- |
+| **Начни здесь** — матрица задач, воркфлоу, чеклисты | `skills/rstool-helper/GUIDE.md`     |
+| API, stdio, MCP, контракт                           | `skills/rstool-helper/REFERENCE.md` |
+| Примеры, антипаттерны                               | `skills/rstool-helper/EXAMPLES.md`  |
+| Язык и предметная область                           | `docs/*.md`                         |
+| Установка skill                                     | `skills/INSTALL.md`                 |
+
+## Задача → что читать
+
+Не читай все `docs/` подряд. Открой **GUIDE.md** (раздел «Задача → чтение»), затем только нужные файлы:
+
+| Задача                            | Минимум                                                                        |
+| :-------------------------------- | :----------------------------------------------------------------------------- |
+| Собрать / развить КС из текста    | GUIDE: концептуализация; `docs/CONCEPTUAL-SCHEMA.md`; `docs/BASE-SELECTION.md` |
+| Оценить / отревьюить готовую КС   | GUIDE: ревью; чеклист ревью; `docs/CONCEPTUAL-SCHEMA.md`                       |
+| Починить формулу / диагностики    | GUIDE: цикл диагностик; `docs/DIAGNOSTICS.md`                                  |
+| Импорт / правка по ссылке Portal  | GUIDE: Portal; `docs/PORTAL-API.md`                                            |
+| Проверить смысл на данных         | GUIDE: КМ; `docs/MODEL-TESTING.md`                                             |
+| Синтаксис / типизация / вызов API | `docs/SYNTAX.md` / `TYPIFICATION.md` / `REFERENCE.md`                          |
+
+Перед работой всегда открой **GUIDE.md**; остальное — по строке таблицы.
 
 ## Не правь пакет rstool без запроса
 
@@ -41,4 +60,5 @@ REST API и curl — `node_modules/@rsconcept/rstool/docs/PORTAL-API.md`.
 ## Кратко
 
 - Пакет: `@rsconcept/rstool`; обёртка: `npx rstool-wrapper`
+- MCP: `@rsconcept/rstool-mcp` (имена tools — `snake_case`, см. REFERENCE)
 - `@rsconcept/domain` устанавливается как зависимость (анализатор и коды ошибок)

package/src/mappers/diagnostic-assembly.ts

@@ -90,6 +90,9 @@ function expressionForCstDiagnostic(cst: Constituenta, diagnostic: CstDiagnostic
       return cst.convention;
     case RSDiagnosticCode.schemaTypeMismatch:
       return cst.typification_manual;
+    case RSDiagnosticCode.schemaDependencyCycle:
+    case RSDiagnosticCode.schemaFormalDuplicate:
+      return cst.definition_formal;
     default:
       return cst.definition_formal;
   }

package/src/mappers/rsform-builder.ts

@@ -75,7 +75,7 @@ export function enrichSessionConstituents(session: SessionState): EnrichedConsti
     }
   }
 
-  assignSchemaDiagnostics(schema.items, resolveAlias, normalizedDefinitions);
+  assignSchemaDiagnostics(schema.items, resolveAlias, normalizedDefinitions, schema.graph);
 
   return session.items.map(item => ({
     item,

package/src/mappers/schema-adapter.ts

@@ -1,6 +1,6 @@
-import { RSLangAnalyzer, type AnalysisFull, type ValueClass } from '@rsconcept/domain/rslang';
 import { getAnalysisFor } from '@rsconcept/domain/library/rsform-api';
-import { CstType, type RSForm } from '@rsconcept/domain/library/rsform';
+import { type RSForm } from '@rsconcept/domain/library/rsform';
+import { RSLangAnalyzer } from '@rsconcept/domain/rslang';
 
 import {
   type AnalysisResult,
@@ -9,6 +9,7 @@ import {
   type Diagnostic,
   type SessionState
 } from '../models';
+import { buildRSFormFromSession } from './rsform-builder';
 import { toPublicAnalysis } from './types';
 
 export class SchemaAdapter {
@@ -16,9 +17,8 @@ export class SchemaAdapter {
     session: SessionState,
     draft: ConstituentaDraft
   ): { result: AnalysisResult; diagnostics: Diagnostic[] } {
-    const analyzer = this.buildAnalyzer(session);
-    const schema = this.toPseudoRSFormState(session, analyzer);
-    const analysis = getAnalysisFor(draft.definitionFormal, draft.cstType, schema as unknown as RSForm, draft.alias);
+    const schema = this.toAnalysisSchema(session, draft);
+    const analysis = getAnalysisFor(draft.definitionFormal, draft.cstType, schema, draft.alias);
     const target = { constituentId: draft.id, alias: draft.alias };
     const result = toPublicAnalysis(
       {
@@ -70,18 +70,50 @@ export class SchemaAdapter {
     };
   }
 
-  private buildAnalyzer(session: SessionState): RSLangAnalyzer {
-    const analyzer = new RSLangAnalyzer();
-    for (const item of session.items) {
-      if (item.cstType === CstType.BASE) {
-        analyzer.addBase(item.alias);
+  /**
+   * Schema view for analysis: session items with the draft expression merged in so the
+   * dependency graph (and cycle diagnostics) reflect the expression under check.
+   */
+  private toAnalysisSchema(session: SessionState, draft: ConstituentaDraft): RSForm {
+    const items = session.items.map(item => {
+      if (item.id !== draft.id) {
+        return item;
       }
-      analyzer.setGlobal(
-        item.alias,
-        item.analysis.type as AnalysisFull['type'],
-        item.analysis.valueClass as ValueClass | null
-      );
+      return {
+        ...item,
+        alias: draft.alias,
+        cstType: draft.cstType,
+        definitionFormal: draft.definitionFormal,
+        term: draft.term ?? item.term,
+        definitionText: draft.definitionText ?? item.definitionText,
+        convention: draft.convention ?? item.convention,
+        // Drop cached type so mutual references surface as untyped → cycle.
+        analysis: {
+          ...item.analysis,
+          success: false,
+          type: null,
+          valueClass: null
+        }
+      };
+    });
+    if (!items.some(item => item.id === draft.id)) {
+      items.push({
+        id: draft.id,
+        alias: draft.alias,
+        cstType: draft.cstType,
+        definitionFormal: draft.definitionFormal,
+        term: draft.term ?? '',
+        definitionText: draft.definitionText ?? '',
+        convention: draft.convention ?? '',
+        analysis: {
+          success: false,
+          type: null,
+          valueClass: null,
+          diagnostics: []
+        }
+      });
     }
-    return analyzer;
+
+    return buildRSFormFromSession({ ...session, items });
   }
 }

package/src/models/agent-workflow.ts

@@ -35,6 +35,14 @@ export interface ApplySchemaPatchInput {
   commitMessage?: string;
 }
 
+/** Result of {@link RSToolAgent.restoreOrder}. */
+export interface RestoreOrderResult {
+  /** Constituent ids in the restored declaration order. */
+  orderedIds: number[];
+  /** Aliases in the same order as {@link orderedIds}. */
+  orderedAliases: string[];
+}
+
 /** Compact view of one constituent in a session summary. */
 export interface SessionSummaryItem {
   id: number;

package/src/models/index.ts

@@ -2,6 +2,7 @@ export {
   type AgentConstituentaPatch,
   type ApplySchemaPatchInput,
   type ApplySchemaPatchResult,
+  type RestoreOrderResult,
   type SessionStateDetail,
   type SessionStateResult,
   type SessionSummary,

package/src/models/rstool-agent.test.ts

@@ -877,6 +877,27 @@ describe('RSToolAgent import and export', () => {
     expect(exported.items.map(item => item.alias)).toEqual(['D1', 'S1', 'C1', 'X1']);
   });
 
+  it('restoreOrder reorders by formal topology and kernel priority', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession({ title: 'Restore', alias: 'RO' });
+    tool.applySchemaPatch(
+      {
+        items: [
+          { alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)\\X1' },
+          { alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' },
+          { alias: 'A2', cstType: CstType.AXIOM, definitionFormal: 'P1[S1]' },
+          { alias: 'P1', cstType: CstType.PREDICATE, definitionFormal: '[α∈ℬ(R1)] card(α)=0' },
+          { alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
+        ]
+      },
+      session.sessionId
+    );
+
+    const result = tool.restoreOrder(session.sessionId);
+    expect(result.orderedAliases.slice(0, 5)).toEqual(['X1', 'P1', 'S1', 'A2', 'D1']);
+    expect(fullState(tool, session.sessionId).items.map(item => item.alias)).toEqual(result.orderedAliases);
+  });
+
   it('round-trips portal schema export and import', () => {
     const tool = new RSToolAgent();
     const session = tool.createSession({ title: 'Round trip', alias: 'RT' });

package/src/models/rstool-agent.ts

@@ -1,3 +1,4 @@
+import { restoreConstituentOrder } from '@rsconcept/domain/library/rsform-api';
 import {
   portalDetailsToDrafts,
   portalDetailsToSessionSeed,
@@ -13,6 +14,7 @@ import {
   type AgentConstituentaPatch,
   type ApplySchemaPatchInput,
   type ApplySchemaPatchResult,
+  type RestoreOrderResult,
   type SessionStateDetail,
   type SessionStateResult,
   type SessionSummary
@@ -303,6 +305,27 @@ export class RSToolAgent implements RSToolAgentContract {
     return result;
   }
 
+  /** @inheritdoc */
+  public restoreOrder(sessionId?: string): RestoreOrderResult {
+    const id = this.resolveSessionId(sessionId);
+    const envelope = this.sessions.get(id);
+    const orderable = envelope.state.items.map(item => ({
+      id: item.id,
+      alias: item.alias,
+      cst_type: item.cstType,
+      definition_formal: item.definitionFormal
+    }));
+    const ordered = restoreConstituentOrder(orderable);
+    const byId = new Map(envelope.state.items.map(item => [item.id, item]));
+    envelope.state.items = ordered.map(item => byId.get(item.id)!);
+    envelope.state.updatedAt = new Date().toISOString();
+    this.sessions.replaceState(id, envelope.state);
+    return {
+      orderedIds: ordered.map(item => item.id),
+      orderedAliases: ordered.map(item => item.alias)
+    };
+  }
+
   private addOrUpdateConstituenta(
     input: AddOrUpdateConstituentaInput,
     sessionId?: string

package/src/models/tool-contract.ts

@@ -1,6 +1,7 @@
 import {
   type ApplySchemaPatchInput,
   type ApplySchemaPatchResult,
+  type RestoreOrderResult,
   type SessionStateDetail,
   type SessionStateResult
 } from './agent-workflow';
@@ -12,7 +13,7 @@ import { type RecalculateModelResult, type SessionModelState, type SetModelValue
 import { type SessionHandle, type SessionRevision, type SessionState } from './session';
 
 /** Agent-visible contract version; bump on breaking API changes. */
-export const CONTRACT_VERSION = '3.0.0';
+export const CONTRACT_VERSION = '3.1.0';
 
 /** Options for constructing an {@link RSToolAgent}. */
 export interface RSToolAgentOptions {
@@ -85,4 +86,10 @@ export interface RSToolAgentContract {
 
   /** Recompute derived model values for all constituents. */
   recalculateModel(sessionId?: string): RecalculateModelResult;
+
+  /**
+   * Restore declaration order: formal topology, semantic clusters when ready,
+   * otherwise stable against type/kernel preferred ranks.
+   */
+  restoreOrder(sessionId?: string): RestoreOrderResult;
 }

package/src/wrapper/stdio-handler.ts

@@ -33,7 +33,8 @@ export const STDIO_METHODS = [
   'setModelValues',
   'getModelState',
   'evaluate',
-  'recalculateModel'
+  'recalculateModel',
+  'restoreOrder'
 ] as const;
 
 function asObject(value: unknown): Record<string, unknown> {
@@ -171,6 +172,12 @@ export async function handleStdioRequest(tool: RSToolAgent, request: StdioReques
           ok: true,
           result: tool.recalculateModel(optionalSessionId(params))
         };
+      case 'restoreOrder':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.restoreOrder(optionalSessionId(params))
+        };
       default:
         return {
           id: request.id ?? null,