@rsconcept/rstool 0.10.3 → 1.0.0

package/skills/rstool-helper/REFERENCE.md

@@ -3,199 +3,62 @@
 ## Контракт rstool
 
 - Пакет: `@rsconcept/rstool`
-- Версия контракта: `1.4.0` (`CONTRACT_VERSION`)
+- Версия контракта: `2.0.0` (`CONTRACT_VERSION`)
 - Основной класс: `RSToolAgent`
 - Публичные импорты: `@rsconcept/rstool` и `@rsconcept/rstool/wrapper`
 
-### Методы
-
-| Метод                                                       | Назначение                                                                    |
-| ----------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `createSession(initial?)`                                   | Новая in-memory сессия → `{ sessionId, contractVersion }`                     |
-| `addOrUpdateConstituenta(sessionId, { draft })`             | Слияние черновика; анализ в контексте сессии → `{ state, diagnostics }`       |
-| `analyzeExpression(sessionId, { expression, cstType })`     | Разбор/типизация фрагмента без сохранения конституенты                        |
-| `getFormState(sessionId)`                                   | Клон полного состояния сессии                                                 |
-| `listDiagnostics(sessionId, filters?)`                      | Накопленные диагностики; опциональный фильтр `constituentId`                  |
-| `commitStep(sessionId, message?)`                           | Зафиксировать контрольную точку ревизии                                       |
-| `exportSession(sessionId)`                                  | JSON-строка `{ contractVersion, state, diagnostics }`                         |
-| `exportPortalSchema(sessionId)`                             | JSON импорта схемы Portal                                                     |
-| `exportPortalModel(sessionId)`                              | JSON импорта модели Portal                                                    |
-| `importSession(payload)`                                    | Новая сессия из экспорта                                                      |
-| `setConstituentaValue(sessionId, { target, type?, value })` | Одна привязка базового понятия или структурное значение → `SessionModelState` |
-| `setConstituentaValues(sessionId, { items })`               | Пакетная установка значений → `SessionModelState`                             |
-| `clearConstituentaValues(sessionId, { items })`             | Очистка значений по id конституент → `SessionModelState`                      |
-| `getModelState(sessionId)`                                  | Клон состояния интерпретации сессии                                           |
-| `evaluateExpression(sessionId, { expression, cstType })`    | Вычисление фрагмента в контексте сессии → `EvaluationResult`                  |
-| `evaluateConstituenta(sessionId, { constituentId })`        | Вычисление сохранённого определения → `EvaluationResult`                      |
-| `recalculateModel(sessionId)`                               | Пересчёт всех выводимых конституент → `{ items[] }`                           |
-
-### `ConstituentaDraft`
-
-```ts
-{
-  id: number;           // стабильный id внутри сессии
-  alias: string;
-  cstType: CstType;
-  definitionFormal: string;
-  term?: string;
-  definitionText?: string;
-  convention?: string;
-}
-```
-
-Пропущенные текстовые поля в сохранённом состоянии по умолчанию `''`.
-
-### Метаданные `SessionState`
-
-Задаются в `createSession(initial?)` или через `importSession`:
-
-```ts
-{
-  alias: string; // alias объекта библиотеки
-  title: string; // отображаемое название
-  comment: string; // заметки разработчика
-}
-```
-
-При опускании все поля по умолчанию `''`.
-
-### Типы модели и вычисления
+### Методы library API
+
+| Метод                                          | Назначение                                   |
+| ---------------------------------------------- | -------------------------------------------- |
+| `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?)`         | Разбор без сохранения (`recordDiagnostics?`) |
+| `commitStep(message?, sessionId?)`             | Ревизия                                      |
+| `exportSession(sessionId?)`                    | JSON сессии                                  |
+| `exportPortal({ kind, format? }, sessionId?)`  | Portal Load from JSON                        |
+| `importData(payload, kind?)`                   | Импорт сессии / Portal                       |
+| `setModelValues({ set?, clear? }, sessionId?)` | Значения модели                              |
+| `getModelState(sessionId?)`                    | Состояние интерпретации                      |
+| `evaluate(input, sessionId?)`                  | Scratch или конституента                     |
+| `recalculateModel(sessionId?)`                 | Пересчёт                                     |
+
+### `applySchemaPatch`
 
 ```ts
-type RSToolValue = number | RSToolValue[]; // значение во время выполнения
-type BasicBinding = Record<number, string>; // подписи элементов базового множества
-
-interface SessionModelState {
-  items: { id: number; type: string; value: RSToolValue | BasicBinding }[];
-}
-
-interface EvaluationResult {
-  success: boolean;
-  value: RSToolValue | BasicBinding | null;
-  status: EvalStatus; // 1=NO_EVAL … 7=HAS_DATA
-  iterations: number;
-  cacheHits: number;
-  diagnostics: { code: number; from: number; to: number; params?: string[] }[];
-}
+tool.applySchemaPatch({
+  initial: { title: 'Kinship' },
+  commitMessage: 'initial schema',
+  items: [{ alias: 'X1' }, { alias: 'S1', definitionFormal: 'ℬ(X1×X1)' }, { alias: 'D1', definitionFormal: 'Pr1(S1)' }]
+});
 ```
 
-Привязки `basic`/`constant` используют `type: "basic"` и `value: { "0": "label", … }`. Структурные значения — нормализованная типизация в `type` и вложенные массивы для множеств/кортежей.
-
 ### Протокол stdio
 
-Процесс: `npx rstool-wrapper`
-
-1. **Ready** (без запроса): `{"id":null,"ok":true,"result":{"ready":true,"wrapper":"rstool-stdio","contractVersion":"1.4.0"}}`
-2. **Запрос**: `{"id":"<unique>","method":"<name>","params":{...}}`
-3. **Ответ**: `{"id":"<same>","ok":true,"result":...}` или `{"id":"...","ok":false,"error":{"code":"...","message":"..."}}`
+Плоские `params` (без `input`). Опционально: переменная окружения `RSTOOL_PERSISTENCE_DIR` — каталог для сохранения сессий между перезапусками обёртки (в library API — `new RSToolAgent({ persistenceDir })`).
 
-Дополнительные методы: `ping`, `methods`.
+Служебные методы:
 
-Пример цепочки:
+- `ping` — liveness и `contractVersion`.
+- `methods` — список доступных stdio-методов.
 
 ```json
-{"id":"1","method":"createSession","params":{}}
-{"id":"2","method":"addOrUpdateConstituenta","params":{"sessionId":"…","input":{"draft":{"id":2,"alias":"S1","cstType":"structure","definitionFormal":"ℬ(X1×X1)"}}}}
-{"id":"2b","method":"addOrUpdateConstituenta","params":{"sessionId":"…","input":{"draft":{"id":3,"alias":"D1","cstType":"term","definitionFormal":"Pr1(S1)"}}}}
-{"id":"3","method":"analyzeExpression","params":{"sessionId":"…","input":{"expression":"1+2","cstType":"term"}}}
-{"id":"4","method":"listDiagnostics","params":{"sessionId":"…"}}
-{"id":"5","method":"commitStep","params":{"sessionId":"…","message":"checkpoint"}}
-{"id":"6","method":"exportSession","params":{"sessionId":"…"}}
-{"id":"6a","method":"exportPortalSchema","params":{"sessionId":"…"}}
-{"id":"6b","method":"exportPortalModel","params":{"sessionId":"…"}}
-{"id":"7","method":"setConstituentaValue","params":{"sessionId":"…","input":{"target":1,"value":{"0":"a","1":"b"}}}}
-{"id":"8","method":"evaluateExpression","params":{"sessionId":"…","input":{"expression":"1+2","cstType":"term"}}}
-{"id":"9","method":"evaluateConstituenta","params":{"sessionId":"…","input":{"constituentId":3}}}
-```
-
-`RSToolWrapperClient`: по умолчанию запускает `rstool-wrapper`; методы `waitUntilReady()`, `call(method, params)`, `close()`.
-
-### Результат анализа
-
-```ts
-interface AnalysisResult {
-  success: boolean;
-  type: Record<string, unknown> | null;
-  valueClass: 'value' | 'property' | null;
-  diagnostics: { code: number; from: number; to: number; params?: string[] }[];
-}
+{"id":"2","method":"applySchemaPatch","params":{"items":[{"alias":"X1"}]}}
+{"id":"7","method":"setModelValues","params":{"set":[{"target":1,"value":{"0":"a"}}]}}
+{"id":"8","method":"evaluate","params":{"constituentId":3}}
+{"id":"9","method":"exportPortal","params":{"kind":"schema"}}
+{"id":"10","method":"importData","params":{"payload":"..."}}
 ```
 
-## RSLang
-
-Кратко: язык на базе логики первого порядка; разделение множественных и логических выражений; параметризованные шаблоны для функций и предикатов.
-
-- **Типизация**: структурный тип выражения; ступени включают элементы (`Xi`, `Ci`), `Z`, кортежи `(H1×…×Hn)`, множества `ℬ(H)`, логику `Logic`, параметризованные `Hr 🠔 [H1,…,Hi]`. У `structure` (`S#`) поле `definitionFormal` **задаёт** типизацию. У `term` (`D#`) типизация **выводится** из определения.
-
-## Токены грамматики
+### MCP tools
 
-Из `rslang.grammar`:
-
-| Категория           | Токены / формы                                          |
-| ------------------- | ------------------------------------------------------- |
-| Глобальные          | `X`, `C`, `S`, `D`, `A`, `T` + цифры (правило `Global`) |
-| Функции / предикаты | `F<n>`, `P<n>`                                          |
-| Радикалы            | `R<n>`                                                  |
-| Локальные           | `_a-zα-ω` + опциональные цифры                          |
-| Логика              | `¬` `∀` `∃` `⇔` `⇒` `∨` `&`                             |
-| Множества           | `ℬ` `∪` `\` `∆` `∩` `×` `∈` `∉` `⊆` `⊂` …               |
-| Операции            | `Pr`, `pr`, `Fi`, `card`, `bool`, `debool`, `red`       |
-| Литералы            | цифры, `Z`, `∅`                                         |
-
-Полная грамматика и приоритеты: `docs/GRAMMAR-REF.md`.
+17 tools — см. `rstool-mcp/README.md`.
 
 ## Документация
 
-| Тема                                     | Документ                                                     |
-| ---------------------------------------- | ------------------------------------------------------------ |
-| Идентификаторы, литералы                 | `docs/SYNTAX.md` § «Имена и литералы»                        |
-| Ступени, `Logic`, параметризованные типы | `docs/TYPIFICATION.md` § «Ступени»                           |
-| Логические выражения                     | `docs/SYNTAX.md` § «Логические выражения (LE)»               |
-| Операторы над множествами                | `docs/SYNTAX.md` § «Теоретико-множественные выражения (STE)» |
-| Целочисленная арифметика                 | `docs/SYNTAX.md` § «Арифметика»                              |
-| Дополнительные и производные типизации   | `docs/TYPIFICATION.md` § «Дополнительные типизации»          |
-| Кванторы                                 | `docs/SYNTAX.md` § «Кванторы»                                |
-| Параметризованные функции, шаблоны       | `docs/SYNTAX.md` § «Параметризованные выражения»             |
-| Модель корректности / валидация          | `docs/SYNTAX.md` § «Корректность»                            |
-| Семантические тесты определений          | `docs/MODEL-TESTING.md`                                      |
-| Словарь предметной области               | `docs/DOMAIN.md`                                             |
-| Поля конституент и порядок               | `docs/CONSTITUENTA.md`                                       |
-| REST API Portal                          | `docs/PORTAL-API.md`                                         |
-| Токены грамматики / приоритеты           | `docs/GRAMMAR-REF.md`                                        |
-
-Воркфлоу и чеклисты — `skills/rstool-helper/GUIDE.md`.
-
-## Коды ошибок
-
-Категории и исправления по коду: `docs/DIAGNOSTICS.md`.
-
-Категории:
-
-- `0x84xx` — синтаксис / разбор
-- `0x28xx` — предупреждения локальных объявлений
-- `0x88xx` — семантика / типы
-- `0x886x` — уровень конституент (пустая производная, запрещённое определение)
-- `0x81xx` — вычисление (runtime; из `evaluateExpression` / `evaluateConstituenta`)
-
-## Форма экспорта сессии
-
-`exportSession(sessionId)` возвращает JSON-строку `{ contractVersion, state, diagnostics }`.
-
-- `state.alias`, `state.title`, `state.comment` — метаданные объекта библиотеки для экспорта в Portal (`comment` → JSON `description`).
-- `state.items[]` — каждая конституента с `id`, `alias`, `cstType`, `definitionFormal`, опциональными текстовыми полями и вложенным результатом анализа.
-- `state.model.items[]` — присутствует, если заданы значения интерпретации.
-- `diagnostics[]` — накопленные диагностики со смещениями и кодами.
-
-`importSession(payload)` принимает только этот формат `exportSession`. JSON Portal из
-`GET /api/rsforms/:id/details` сначала переноси в сессию через `createSession` и
-`addOrUpdateConstituenta`; поля и REST-пути описаны в `docs/PORTAL-API.md`.
-
-## JSON импорта Portal
-
-Для **Load from JSON** на существующей схеме или модели Portal:
-
-- `exportPortalSchema(sessionId)` — файл схемы
-- `exportPortalModel(sessionId)` — файл модели
-
-- Схема `items[]`: поля конституент (`cst_type`, `definition_formal`, `term_raw`, …).
-- Модель `items[]`: `{ id, type, value }` на каждую привязку.
+Воркфлоу: `GUIDE.md`. Примеры: `EXAMPLES.md`. Язык: `docs/*.md`.

package/src/index.ts

@@ -1,9 +1,10 @@
-export {
-  toPublicAnalysis,
-  toPublicError,
-  type DomainAnalysisLike,
-  type DomainErrorLike
-} from './mappers/types';
+/**
+ * Public API for `@rsconcept/rstool`.
+ *
+ * Primary entry points: {@link RSToolAgent} (in-process) and {@link RSToolWrapperClient}
+ * (stdio child process). Types describe the v2 agent contract.
+ */
+export { toPublicAnalysis, toPublicError, type DomainAnalysisLike, type DomainErrorLike } from './mappers/types';
 export {
   CONTRACT_VERSION,
   CstType,
@@ -11,39 +12,45 @@ export {
   RSErrorCode,
   RSToolAgent,
   ValueClass,
-  type AddOrUpdateConstituentaInput,
-  type AddOrUpdateConstituentaResult,
+  type AgentConstituentaPatch,
   type AnalysisResult,
   type AnalyzeExpressionInput,
+  type ApplySchemaPatchInput,
+  type ApplySchemaPatchResult,
   type BasicBinding,
-  type ClearConstituentaValuesInput,
   type ConstituentaDraft,
   type ConstituentaState,
   type DiagnosticRecord,
-  type EvaluateConstituentaInput,
-  type EvaluateExpressionInput,
+  type EvaluateInput,
   type EvaluationResult,
+  type ExportFormat,
+  type ExportPortalInput,
+  type ExportPortalResult,
+  type ImportDataKind,
   type ListDiagnosticsFilters,
   type ModelValueState,
   PORTAL_JSON_CONTRACT_VERSION,
+  type PortalExportKind,
   type PortalImportMetadata,
   type PortalModelImportData,
+  type PortalRsformDetails,
   type PortalSchemaConstituenta,
   type PortalSchemaImportData,
   type PortalTermForm,
   type RecalculateModelResult,
   type RSToolAgentContract,
+  type RSToolAgentOptions,
   type RSToolErrorDescription,
   type RSToolValue,
   type SessionHandle,
   type SessionModelState,
   type SessionRevision,
+  type SessionStateDetail,
+  type SessionStateResult,
+  type SessionSummary,
+  type SessionSummaryItem,
   type SessionState,
   type SetConstituentaValueInput,
-  type SetConstituentaValuesInput
+  type SetModelValuesInput
 } from './models';
-export {
-  RSToolWrapperClient,
-  type RSToolWrapperClientOptions,
-  type WrapperResponse
-} from './wrapper/client';
+export { RSToolWrapperClient, type RSToolWrapperClientOptions, type WrapperResponse } from './wrapper/client';

package/src/mappers/portal-adapter.ts

@@ -0,0 +1,43 @@
+import { type ConstituentaDraft } from '../models/constituenta';
+import { type PortalRsformDetails, type PortalSchemaImportData, portalItemToDraft } from '../models/portal-json';
+import { type SessionState } from '../models/session';
+
+export function portalSchemaToSessionSeed(data: PortalSchemaImportData): Partial<SessionState> {
+  return {
+    alias: data.alias ?? '',
+    title: data.title ?? '',
+    comment: data.description ?? '',
+    items: []
+  };
+}
+
+export function portalDetailsToSessionSeed(data: PortalRsformDetails): Partial<SessionState> {
+  return {
+    alias: data.alias ?? '',
+    title: data.title ?? '',
+    comment: data.description ?? '',
+    items: []
+  };
+}
+
+export function portalItemsToDrafts(
+  items: Array<{
+    id: number;
+    alias: string;
+    cst_type: string;
+    definition_formal?: string;
+    term_raw?: string;
+    definition_raw?: string;
+    convention?: string;
+  }>
+): ConstituentaDraft[] {
+  return items.map(item => portalItemToDraft(item));
+}
+
+export function portalSchemaToDrafts(data: PortalSchemaImportData): ConstituentaDraft[] {
+  return portalItemsToDrafts(data.items);
+}
+
+export function portalDetailsToDrafts(data: PortalRsformDetails): ConstituentaDraft[] {
+  return portalItemsToDrafts(data.items);
+}

package/src/mappers/types.ts

@@ -2,6 +2,7 @@ import { type ValueClass } from '@rsconcept/domain/rslang';
 
 import { type AnalysisResult, type RSToolErrorDescription } from '../models';
 
+/** Minimal domain error shape before mapping to {@link RSToolErrorDescription}. */
 export interface DomainErrorLike {
   code: number;
   from: number;
@@ -9,6 +10,7 @@ export interface DomainErrorLike {
   params?: readonly string[];
 }
 
+/** Minimal domain analysis shape before mapping to {@link AnalysisResult}. */
 export interface DomainAnalysisLike {
   success: boolean;
   type: Record<string, unknown> | null;
@@ -16,6 +18,7 @@ export interface DomainAnalysisLike {
   errors: DomainErrorLike[];
 }
 
+/** Map a domain parser/semantic error to the public diagnostic shape. */
 export function toPublicError(error: DomainErrorLike): RSToolErrorDescription {
   return {
     code: error.code,
@@ -25,6 +28,7 @@ export function toPublicError(error: DomainErrorLike): RSToolErrorDescription {
   };
 }
 
+/** Map a domain analysis result to the public {@link AnalysisResult} shape. */
 export function toPublicAnalysis(analysis: DomainAnalysisLike): AnalysisResult {
   return {
     success: analysis.success,

package/src/models/agent-workflow.ts

@@ -0,0 +1,78 @@
+import { type CstType } from './common';
+import {
+  type ApplyConstituentsMode,
+  type ApplyConstituentsResult,
+  type ConstituentaDraft,
+  type ConstituentaState
+} from './constituenta';
+import { type DiagnosticRecord } from './diagnostic';
+import { type SessionHandle, type SessionRevision, type SessionState } from './session';
+
+/** Level of detail returned by {@link RSToolAgent.getSessionState}. */
+export type SessionStateDetail = 'summary' | 'full';
+
+/** Result of `getSessionState`: compact summary or full cloned session state. */
+export type SessionStateResult = SessionSummary | SessionState;
+
+/**
+ * Partial constituent update used in {@link ApplySchemaPatchInput}.
+ *
+ * `alias` is required; other fields are merged with any existing constituent
+ * or inferred from the alias prefix when omitted.
+ */
+export interface AgentConstituentaPatch extends Omit<Partial<ConstituentaDraft>, 'alias'> {
+  alias: string;
+}
+
+/** Input for {@link RSToolAgent.applySchemaPatch}. */
+export interface ApplySchemaPatchInput {
+  /** Metadata used only when a new session is created for this patch. */
+  initial?: {
+    alias?: string;
+    title?: string;
+    comment?: string;
+  };
+  /** Constituent patches to apply in dependency order. */
+  items: AgentConstituentaPatch[];
+  /** atomic: rollback on first failure; best_effort applies valid drafts. Default: atomic. */
+  mode?: ApplyConstituentsMode;
+  /** When set, a revision is recorded after a successful patch. */
+  commitMessage?: string;
+}
+
+/** Compact view of one constituent in a session summary. */
+export interface SessionSummaryItem {
+  id: number;
+  alias: string;
+  cstType: CstType;
+  analysisSuccess: boolean;
+}
+
+/** Compact session overview returned by default from `getSessionState`. */
+export interface SessionSummary {
+  sessionId: string;
+  contractVersion: string;
+  alias: string;
+  title: string;
+  comment: string;
+  itemCount: number;
+  modelItemCount: number;
+  diagnosticsCount: number;
+  items: SessionSummaryItem[];
+  diagnostics: DiagnosticRecord[];
+  lastRevision?: SessionRevision;
+}
+
+/** Result of {@link RSToolAgent.applySchemaPatch}. */
+export interface ApplySchemaPatchResult extends ApplyConstituentsResult {
+  session: SessionHandle;
+  summary: SessionSummary;
+  revision?: SessionRevision;
+}
+
+/** Internal: resolved patch with previous state for undo bookkeeping. */
+export interface ResolvedAgentPatch {
+  patch: AgentConstituentaPatch;
+  draft: ConstituentaDraft;
+  previous?: ConstituentaState;
+}

package/src/models/analysis.ts

@@ -1,12 +1,19 @@
 import { type CstType, type RSToolErrorDescription, type ValueClass } from './common';
 
+/** Input for {@link RSToolAgent.analyzeExpression}. */
 export interface AnalyzeExpressionInput {
+  /** RSLang expression to parse and type-check. */
   expression: string;
+  /** Expected constituent type context for the expression. */
   cstType: CstType;
+  /** When true, append diagnostics to the session log. Default: false. */
+  recordDiagnostics?: boolean;
 }
 
+/** Outcome of parsing and semantic analysis for one expression. */
 export interface AnalysisResult {
   success: boolean;
+  /** Inferred RS type AST as a plain object, or `null` on failure. */
   type: Record<string, unknown> | null;
   valueClass: ValueClass | null;
   diagnostics: RSToolErrorDescription[];

package/src/models/common.ts

@@ -3,15 +3,22 @@ import { EvalStatus, type BasicBinding } from '@rsconcept/domain/library/rsmodel
 import { ValueClass } from '@rsconcept/domain/rslang';
 import { RSErrorCode } from '@rsconcept/domain/rslang/error';
 
+/** Constituent type enum (X, D, C, …). Re-exported from `@rsconcept/domain`. */
 export { CstType, EvalStatus, RSErrorCode, ValueClass };
+/** Named binding used in model evaluation. Re-exported from `@rsconcept/domain`. */
 export type { BasicBinding };
 
 /** Runtime evaluation value: number, nested array (set/tuple), or boolean 0/1. */
 export type RSToolValue = number | RSToolValue[];
 
+/** Language or validation error with source span and optional format parameters. */
 export interface RSToolErrorDescription {
+  /** Numeric error code (see {@link RSErrorCode}). */
   code: number;
+  /** Start offset in the analyzed expression. */
   from: number;
+  /** End offset in the analyzed expression. */
   to: number;
+  /** Interpolation values for localized error messages. */
   params?: readonly string[];
 }

package/src/models/constituenta.ts

@@ -2,22 +2,24 @@ import { type AnalysisResult } from './analysis';
 import { type CstType } from './common';
 import { type DiagnosticRecord } from './diagnostic';
 
+/** Constituent payload before analysis and merge into session state. */
 export interface ConstituentaDraft {
   id: number;
-  /** Alias */
+  /** Unique alias (e.g. `X1`, `D2`). */
   alias: string;
-  /** CST type */
+  /** Constituent type. */
   cstType: CstType;
-  /** Formal definition */
+  /** Formal RSLang definition. */
   definitionFormal: string;
-  /** Natural-language term */
+  /** Natural-language term. */
   term?: string;
-  /** Natural-language definition */
+  /** Natural-language definition. */
   definitionText?: string;
-  /** Convention or comment */
+  /** Convention or comment. */
   convention?: string;
 }
 
+/** Constituent stored in session state after analysis. */
 export interface ConstituentaState extends Omit<ConstituentaDraft, 'term' | 'definitionText' | 'convention'> {
   term: string;
   definitionText: string;
@@ -33,3 +35,19 @@ export interface AddOrUpdateConstituentaResult {
   state: ConstituentaState;
   diagnostics: DiagnosticRecord[];
 }
+
+/** How a multi-draft apply handles partial failures. */
+export type ApplyConstituentsMode = 'atomic' | 'best_effort';
+
+export interface ApplyConstituentsInput {
+  drafts: ConstituentaDraft[];
+  /** atomic: rollback on first failure; best_effort: apply valid drafts. Default: atomic. */
+  mode?: ApplyConstituentsMode;
+}
+
+export interface ApplyConstituentsResult {
+  success: boolean;
+  applied: ConstituentaState[];
+  failed: Array<{ draft: ConstituentaDraft; diagnostics: DiagnosticRecord[] }>;
+  diagnostics: DiagnosticRecord[];
+}

package/src/models/diagnostic.ts

@@ -1,12 +1,16 @@
 import { type RSToolErrorDescription } from './common';
 
+/** Persisted diagnostic for a failed or warned expression in a session. */
 export interface DiagnosticRecord {
   sessionId: string;
+  /** Constituent id when the diagnostic is tied to a stored item; omitted for scratch analysis. */
   constituentId?: number;
+  /** Expression text that was analyzed. */
   expression: string;
   error: RSToolErrorDescription;
 }
 
+/** Filters for {@link RSToolAgent.listDiagnostics}. */
 export interface ListDiagnosticsFilters {
   constituentId?: number;
 }

package/src/models/evaluation.ts

@@ -15,6 +15,17 @@ export interface EvaluateConstituentaInput {
   constituentId: number;
 }
 
+/** Evaluate a scratch expression or a stored constituent (provide one variant). */
+export interface EvaluateInput {
+  /** Scratch expression; requires `cstType`. */
+  expression?: string;
+  /** Type context when evaluating `expression`. */
+  cstType?: CstType;
+  /** Stored constituent id to evaluate. */
+  constituentId?: number;
+}
+
+/** Outcome of model evaluation for one expression or constituent. */
 export interface EvaluationResult {
   success: boolean;
   value: RSToolValue | BasicBinding | null;

package/src/models/import-detect.ts

@@ -0,0 +1,39 @@
+import { type ImportDataKind } from './import-export';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function parseImportPayload(payload: string | object): unknown {
+  if (typeof payload === 'string') {
+    return JSON.parse(payload) as unknown;
+  }
+  return payload;
+}
+
+export function detectImportKind(data: unknown): Exclude<ImportDataKind, 'auto'> {
+  if (!isRecord(data)) {
+    throw new Error('Invalid import payload');
+  }
+
+  if ('contractVersion' in data && 'state' in data) {
+    return 'session';
+  }
+
+  if ('contract_version' in data && Array.isArray(data.items)) {
+    const items = data.items as unknown[];
+    if (items.length > 0 && isRecord(items[0]) && 'cst_type' in items[0]) {
+      return 'portal-schema';
+    }
+    throw new Error('Portal model JSON cannot be imported as a schema session');
+  }
+
+  if (Array.isArray(data.items) && data.items.length > 0) {
+    const first = data.items[0];
+    if (isRecord(first) && 'cst_type' in first) {
+      return 'portal-details';
+    }
+  }
+
+  throw new Error('Cannot detect import kind; pass kind explicitly');
+}