@rsconcept/rstool 0.2.1 → 0.3.0

package/docs/SYNTAX.md

@@ -1,139 +1,84 @@
-# RSLang syntax reference
+# Синтаксис RSLang
 
-Use this when constructing or repairing RSLang expressions. For full grammar tokens see `GRAMMAR-REF.md`. For typification rules see `TYPIFICATION.md`.
+Читай, когда строишь или исправляешь `definitionFormal`. Токены и приоритеты — в `GRAMMAR-REF.md`, типизация — в `TYPIFICATION.md`.
 
-## Identifier rules
+## Имена и литералы
 
-- **Globals** (concept aliases): uppercase Latin letter + digits — `X1`, `C2`, `S3`, `D11`, `F7`, `P4`, `A6`, `T9`, `N12`. The leading letter must match the constituent's role.
-- **Radicals**: identifiers starting with `R` — used inside template parameterised expressions to denote arbitrary typifications (`R1`, `R2`).
-- **Locals** (bound variables): lowercase Latin or Greek letter, optionally with digits — `x`, `ξ`, `μ2`, `y1`.
-- **Special identifiers** — reserved tokens (`Z`, `∅`, operators).
+- Глобальные алиасы: `X1`, `C2`, `S3`, `D11`, `F7`, `P4`, `A6`, `T9`; буква совпадает с ролью.
+- Радикалы: `R1`, `R2` — шаблонные ступени в параметрах.
+- Локальные переменные: `x`, `ξ`, `μ2`, `y1`.
+- Целые: `0`, `42`; отрицательного литерала нет, пиши `0 - 5`.
+- `Z` — множество целых, `∅` — пустое множество с типизацией `ℬ(R0)`.
 
-## Literals
+## Теоретико-множественные выражения (STE)
 
-- **Integers**: digit sequence, no negative literal: `0`, `42`. Negation is a binary subtraction `0 - n`.
-- **Integer set**: `Z`.
-- **Empty set**: `∅` (typification `ℬ(R0)` — set of arbitrary element structure).
+- `D1 ∪ D2`, `D1 ∩ D2`, `D1 \ D2`, `D1 ∆ D2` — операции над множествами.
+- `X1 × X2` — декартово произведение.
+- `ℬ(X1)` — булеан, множество всех подмножеств.
+- `(a, b, c)` — кортеж, арность минимум 2.
+- `{a, b, c}` — перечисление.
+- `bool(a)` — синглетон, `debool(S)` — извлечение единственного элемента.
+- `red(S)` — суммарное множество; `S` должно иметь ступень `ℬ(ℬ(H))`.
+- `pr1(tuple)` — малая проекция кортежа.
+- `Pr1(S)` — большая проекция множества кортежей.
+- `Fi1[D](S)` — фильтр по принадлежности выбранной проекции в `D`.
 
-## Set-theoretic expressions
+Мультииндексы разрешены: `pr1,3(...)`, `Pr2,4(S1)`, `Fi1,2[D1](S1)`.
 
-| Construct            | Syntax              | Notes                                           |
-| -------------------- | ------------------- | ----------------------------------------------- |
-| Union                | `D1 ∪ D2`           |                                                 |
-| Intersection         | `D1 ∩ D2`           |                                                 |
-| Difference           | `D1 \ D2`           |                                                 |
-| Symmetric difference | `D1 ∆ D2`           |                                                 |
-| Cartesian product    | `X1 × X2`           | typification: tuple                             |
-| Boolean / power set  | `ℬ(X1)`             | set of all subsets                              |
-| Tuple                | `(a, b, c)`         | ordered, n ≥ 2                                  |
-| Enumeration          | `{a, b, c}`         | unordered, n ≥ 1                                |
-| Singleton            | `bool(a)` ≡ `{a}`   |                                                 |
-| Desingleton          | `debool({a})` ≡ `a` | only for one-element sets                       |
-| Sum set              | `red(S1)`           | union of inner sets; `S1` must be a set of sets |
-| Small projection     | `pr1((a1, …, an))`  | returns `a1`                                    |
-| Large projection     | `Pr1(S1)`           | set of first components of tuples in `S1`       |
-| Filter               | `Fi1[D1](S1)`       | subset of `S1` whose first projection ∈ `D1`    |
+## Логические выражения (LE)
 
-Indices `1` may be any natural number or comma-separated multi-index (`pr1,3((a1, a2, a3, a4)) = (a1, a3)`, `Fi1,2[D1](S1)`).
+- Предикаты множеств: `ξ ∈ S`, `ξ ∉ S`, `S1 = S2`, `S1 ≠ S2`, `S1 ⊆ S2`, `S1 ⊂ S2`, `S1 ⊄ S2`.
+- Арифметические предикаты: `=`, `≠`, `<`, `≤`, `>`, `≥` над `Z`.
+- Связки: `¬A`, `A & B`, `A ∨ B`, `A ⇒ B`, `A ⇔ B`.
 
-## Logical expressions
+`TRUE` и `FALSE` в экспликации КС не используют.
 
-### Set-theoretic predicates
+## Кванторы
 
-| Predicate        | Syntax    |
-| ---------------- | --------- |
-| Membership       | `ξ ∈ S`   |
-| Non-membership   | `ξ ∉ S`   |
-| Set equality     | `S1 = S2` |
-| Set inequality   | `S1 ≠ S2` |
-| Inclusion        | `S1 ⊆ S2` |
-| Strict inclusion | `S1 ⊂ S2` |
-| Non-inclusion    | `S1 ⊄ S2` |
+- `∀ξ∈D1 (LE(ξ))` — всеобщность.
+- `∃ξ∈D1 (LE(ξ))` — существование.
+- `∀(ξ1, ξ2)∈S1 (LE(ξ1, ξ2))` — объявление кортежа.
+- `∀ξ1, ξ2∈D1 (LE(ξ1, ξ2))` — сокращение вложенных кванторов.
 
-### Arithmetic predicates (typification `Logic`)
+Скобки вокруг `LE` можно опустить для атомарного логического выражения.
 
-`a = b`, `a ≠ b`, `a < b`, `a ≤ b`, `a > b`, `a ≥ b`.
+## Арифметика
 
-### Connectives
+`a + b`, `a - b`, `a * b` дают `Z`. `card(S)` возвращает мощность конечного множества.
 
-| Connective  | Syntax  |
-| ----------- | ------- |
-| Negation    | `¬A`    |
-| Conjunction | `A & B` |
-| Disjunction | `A ∨ B` |
-| Implication | `A ⇒ B` |
-| Equivalence | `A ⇔ B` |
+## Параметризованные выражения
 
-The constants `TRUE` and `FALSE` are **not** used inside schema explications.
-
-## Quantifiers
-
-| Form          | Syntax                       |
-| ------------- | ---------------------------- |
-| Universal     | `∀ξ∈STE (LE(ξ))`             |
-| Existential   | `∃ξ∈STE (LE(ξ))`             |
-| Tuple binding | `∀(ξ1, ξ2)∈STE (LE(ξ1, ξ2))` |
-| Variable list | `∀ξ1, ξ2 ∈ STE (LE(ξ1, ξ2))` |
-
-Parentheses around `LE` may be omitted for atomic logical expressions.
-
-## Arithmetic
-
-Operations `a + b`, `a - b`, `a * b` form set-theoretic expressions with typification `Z`. Negative numbers are computed, never literal.
-
-`card(S)` returns the integer cardinality of `S` (always finite in practice).
-
-## Parameterised expressions
-
-### Term-function declaration
-
-```
+```text
 F1 ::= [α1∈STE1, α2∈STE2(α1)] STE(α1, α2)
-```
-
-- Inside `[]` is an ordered list of parameter declarations separated by commas.
-- A parameter is declared with `∈`: `local_var ∈ domain`.
-- A declared variable can appear in subsequent parameter domains and in the result STE.
-
-### Predicate-function declaration
-
-```
 P1 ::= [α1∈STE1, α2∈STE2(α1)] LE(α1, α2)
 ```
 
-The only difference from a term-function is that the body is a logical expression.
+- В `[]` идут параметры через `∈`.
+- Параметр доступен в следующих доменах и теле.
+- Вызов позиционный: `F1[ξ1, S1]`, `P1[ξ1\ξ2, ξ3]`.
+- `F#` возвращает теоретико-множественное выражение, `P#` — логическое.
 
-### Calling parameterised functions
+## Радикалы
 
-`F1[ξ1, S1]`, `P1[ξ1\ξ2, ξ3]` — arguments are positional and listed in square brackets after the function name. Argument typifications are checked against parameter typifications. Result is an STE (term-function) or LE (predicate-function).
-
-### Template expressions
-
-Functions that use radicals as parameter typifications are templates:
-
-```
+```text
 F2 ::= [α1∈R1×R2, α2∈R1] α2 = pr1(α1)
 ```
 
-- Radical values are **inferred** from the call-site argument typifications. All inferred values for the same radical index must agree.
-- Different radical indices are independent.
-- Radicals may only appear in parameter domains — never in the result expression.
+- `R#` выводится по типизациям аргументов в месте вызова.
+- Все вхождения одного `R#` должны совпасть.
+- Радикалы допустимы только в доменах параметров.
 
-## Examples
+## Примеры
 
 - `¬α ∈ S1`
-- `D1 ∈ S1 ⇒ 2 + 2 = 5`
 - `D1 ⊆ D2 ⇔ ∀x∈D1 x∈D2`
 - `∀x∈D1 ∃y∈D2 (x, y)∈S1 & (x, x)∈S1`
 - `(4 + 5) * 3`, `card(X1) > 5`
-- `ℬ(2) = {{}, {1}, {2}, {1, 2}}`
 - `pr2((5, 4, 3, 2, 1)) = 4`
 - `red({{1, 2, 3}, {3, 4}}) = {1, 2, 3, 4}`
-- `Fi2[{2, 4}]({((1, 2), (3, 4), (5, 6))}) = {((1, 2), (3, 4))}`
 
-## Correctness model
+## Корректность
 
-- Expression checking happens in the **global context**: known typifications and bijective portability of every referenced identifier. Unknown identifiers are errors.
-- Set-theoretic rules follow from bijective portability of the membership predicate — an element must match the typification of the set it is tested against.
-- Logical consistency cannot generally be checked automatically. The existence of an interpretation example in a conceptual model is a basis for accepting consistency.
-- All formal definitions must be **bijectively portable**: values are independent of any bijective replacement of undefined-concept interpretations.
+- Анализ идет в глобальном контексте: все алиасы должны быть известны и типизированы.
+- Формальные определения должны быть биективно переносимыми (гарантируется семантическим анализатором).
+- Логическая непротиворечивость проверяется примером интерпретации в модели.

package/docs/TYPIFICATION.md

@@ -1,84 +1,65 @@
-# Typification reference
+# Типизация
 
-Distilled from `help-rslang-typification`, `help-rslang-expression-structure`, and `help-rslang-expression-parameter`. Agents must understand grades to interpret `AnalysisResult.type` and to construct correct expressions.
+Читай, когда разбираешь `AnalysisResult.type`, `valueClass` или радикалы.
 
-## Grades
+## Ступени
 
-A genus-structure expression `ξ` has typification (a _structure_) if `ξ ∈ H` holds, where `H` is a valid **grade**. Grades are built recursively:
+Выражение типизировано, если его значения принадлежат ступени `H`.
 
-| Grade            | Form                 | Notes                                |
-| ---------------- | -------------------- | ------------------------------------ |
-| Element          | `Xi`, `Ci`           | grade of a basic concept's elements  |
-| Integer          | `Z`                  | grade of integer                     |
-| Tuple of arity n | `(H1 × H2 × … × Hn)` | ordered structured grade             |
-| Set              | `ℬ(H)`               | unordered set of values of grade `H` |
+- `Xi`, `Ci` — элемент базисного или константного множества.
+- `Z` — целое число.
+- `(H1 × H2 × ... × Hn)` — кортеж.
+- `ℬ(H)` — множество значений ступени `H`.
 
-The empty set `∅` has typification `ℬ(R0)` — a set with arbitrary element structure. The radical `R0` ensures it conforms to any element grade in context.
+`∅` имеет типизацию `ℬ(R0)`: пустое множество подстраивается под контекст.
 
-## Extended typifications
+## Дополнительные типизации
 
-Beyond set-theoretic grades, RSLang uses two additional grade-like markers:
+- `Logic` — логические выражения: аксиомы, высказывания, тела предикат-функций.
+- `Hr <- [H1, H2, ..., Hi]` — параметризованная типизация функций: результат и аргументы.
 
-- **Logic** — typification of logical expressions (axioms, statements, predicate bodies) that evaluate to TRUE or FALSE.
-- **Parameterised** — typification of term-functions and predicate-functions:
+## Радикалы
 
-  ```
-  Hr 🠔 [H1, H2, …, Hi]
-  ```
+`R1`, `R2`, ... — шаблонные ступени.
 
-  where `Hr` is the result typification (an STE grade or `Logic`) and `H1 … Hi` are the argument typifications.
+- Значение `R#` выводится по аргументам в месте вызова.
+- Все вхождения одного `R#` должны дать одну ступень.
+- Разные `R#` независимы.
+- Радикалы можно писать только в доменах параметров; в теле результата будет `radicalUsage`.
 
-## Radicals
+## `AnalysisResult.type`
 
-Template parameterised expressions may contain notations `R1, R2, …` (and `R0` for `∅`). Each radical corresponds to an arbitrary grade that is **inferred** from the typifications of the arguments at the point of use.
+`type` приходит как JSON анализатора: `Record<string, unknown> | null`.
 
-- All occurrences of the same radical index must resolve to the same grade.
-- Radicals with different indices are independent.
-- Radicals may only appear in parameter domains, **not in the result expression**.
+Правила:
 
-## Encoded shape in `AnalysisResult.type`
+1. Сначала проверь `analysis.success === true` и `analysis.type !== null`.
+2. Не разбирай объект вручную; используй helpers из `@rsconcept/domain`.
+3. `valueClass` уточняет вычислимость: `Value`, `Property`, `Invalid`.
 
-The contract exposes `type: Record<string, unknown> | null` because typifications are JSON-encoded by the analyzer. Useful properties exposed by `@rsconcept/domain` helpers:
+Полезные API: `TypeID`, `TypePath`, `makeTypePath`, `parseTypeText(...)`.
 
-- `TypeID` enum: `Element`, `Integer`, `Tuple`, `Boolean`, `Logic`, `Functional` — discriminates the top-level shape.
-- `TypePath` (sequence of indices) addresses positions inside a tuple-of-sets-of-tuples structure; use `makeTypePath` to construct.
-- `parseTypeText(...)` parses an ASCII representation `B(X1)`, `(X1×X2)`, etc., into a `Typification`.
+## `S#` и `D#`
 
-For agents inspecting types from rstool output:
+- У `structure` (`S#`) `definitionFormal` читается как типизация. `ℬ(X1×X1)` описывает множество пар.
+- У `term` (`D#`) `definitionFormal` читается как определение. `X1×X1` строит декартов продукт.
 
-1. Check `analysis.success === true` and `analysis.type !== null`.
-2. Use `analysis.type` (object) only as opaque input to `@rsconcept/domain` helpers — do not pattern-match it manually.
-3. The `valueClass` companion indicates `Value`, `Property` (non-computable membership only), or `Invalid`.
+Для отношений предпочитай `S#` с `ℬ(X1×X1)` и конвенцией; выводимые понятия делай через `Pr*`, `Fi*`, фильтры и функции.
 
-## Typification on `S#` vs definition on `D#`
+## Операции
 
-- On a **`structure`** (`S#`), `definitionFormal` is read as **typification**. Subexpressions such as `X1×X1` describe **element shape** (here: one pair of base elements).
-- On a **`term`** (`D#`), the same token sequence is a **definition** evaluated in the model. `X1×X1` alone is the Cartesian product — all ordered pairs from `X1` — not the typification of a relation stored in `S#`.
+Создают ступень: `ℬ(H)`, `H1 × H2`, `(a, b)`, `{a, b}`, `bool(a)`.
 
-Prefer `S#` with `ℬ(X1×X1)` plus `convention` for relations; derive `D#` with `Pr*`, `Fi*`, filters, etc.
+Требуют подходящую ступень:
 
-## Forming structures vs. derived structures
+- `red(S)` — нужно `S : ℬ(ℬ(H))`.
+- `debool(S)` — нужно одноэлементное множество.
+- `pr1(tuple)`, `Pr1(S)` — нужна достаточная арность.
+- `Fi1[D](S)` — `D` должен соответствовать выбранной проекции.
 
-Forming operations build a new grade:
+## Частые ошибки
 
-- `ℬ(H)` — power set
-- `H1 × H2` — Cartesian product
-- `(a, b, c)` — tuple
-- `{a, b, c}` — enumeration
-- `bool(a)` — singleton
-
-Derived structures consume a grade:
-
-- `red(S)` — union of inner sets; requires `S : ℬ(ℬ(H))`
-- `debool({a})` — extracts the single element of a singleton
-- `pr1((a1, …, an))`, `Pr1(S)` — projections (multi-indices allowed: `pr1,3`, `Pr2,4`)
-- `Fi1[D](S)` — filters by membership in `D`; multi-index variants must match parameter arity
-
-## Common typification pitfalls
-
-- Negative integer literals do not exist — use `0 - n`.
-- `debool(S)` fails if `S` is not a singleton.
-- Tuple projections require the argument to be a tuple of sufficient arity; `pr3((a, b))` is an error.
-- Filter parameter list arity must match the multi-index in `Fi[...]`.
-- A radical in the **result expression** of a template is a hard error (`radicalUsage`).
-- An `axiom` or `statement` must have typification `Logic`; non-logical formal definitions raise `expectedLogic`.
+- `debool(S)` без гарантии синглетона.
+- `pr3((a, b))`: индекс вне арности.
+- `Fi1,2[D](S)`: параметр `D` не совпал с двумя проекциями.
+- `A#` и `T#` не имеют `Logic`: будет `expectedLogic`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsconcept/rstool",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Agent-facing library for incremental RSForm construction, RSLang analysis, diagnostics, modeling, and evaluation. Wraps @rsconcept/domain with a deterministic session contract and stdio wrapper.",
   "license": "MIT",
   "author": "IRBorisov",

package/skills/README.md

@@ -4,14 +4,12 @@ Each skill lives in its own subdirectory: `skills/<skill-name>/SKILL.md` (plus r
 
 ## Layout
 
-| Path | Role |
-| :--- | :--- |
-| `INSTALL.md` | **Agent procedure** after `npm install` |
-| `rstool-helper/SKILL.md` | Thin **entry** skill — copy into the project’s agent skills folder (see `INSTALL.md`) |
-| `rstool-helper/GUIDE.md` | Canonical workflow and language primer |
-| `rstool-helper/REFERENCE.md` | API, stdio, contract |
-| `rstool-helper/EXAMPLES.md` | Worked examples and pitfalls |
-| `../docs/*.md` | Language reference (DOMAIN, SYNTAX, DIAGNOSTICS, …) |
+- `INSTALL.md`: agent procedure after `npm install`
+- `rstool-helper/SKILL.md`: thin entry skill — copy into the project’s agent skills folder (see `INSTALL.md`)
+- `rstool-helper/GUIDE.md`: canonical workflow and language primer
+- `rstool-helper/REFERENCE.md`: API, stdio, contract
+- `rstool-helper/EXAMPLES.md`: worked examples and pitfalls
+- `../docs/*.md`: language reference (DOMAIN, SYNTAX, DIAGNOSTICS, …)
 
 ## npm workflow
 

package/skills/rstool-helper/EXAMPLES.md

@@ -1,16 +1,10 @@
-# rstool — worked examples
+# rstool Examples
 
-Install first:
+Short examples for agents. For full scripts, see `../../examples/`.
 
-```bash
-npm install @rsconcept/rstool
-```
-
-## Kinship-lite: structure vs term
-
-`S1` carries **typification** `ℬ(X1×X1)` (pairs over people); `D1` is a **definition** `Pr1(S1)` (parents). Do not put `X1×X1` on a `term` — that is the full Cartesian product.
+## Minimal Session
 
-## In-process
+`S1` carries typification `ℬ(X1×X1)` for relation pairs. `D1` computes `Pr1(S1)`. Do not put bare `X1×X1` on a `term` when you mean a relation structure.
 
 ```ts
 import { CstType, RSToolAgent } from '@rsconcept/rstool';
@@ -18,12 +12,10 @@ import { CstType, RSToolAgent } from '@rsconcept/rstool';
 const tool = new RSToolAgent();
 const { sessionId } = tool.createSession();
 
-// Base set — formal must be empty
 tool.addOrUpdateConstituenta(sessionId, {
   draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
 });
 
-// Structure: typification of parent–child pairs (undefined; convention in real schemas)
 tool.addOrUpdateConstituenta(sessionId, {
   draft: {
     id: 2,
@@ -34,32 +26,33 @@ tool.addOrUpdateConstituenta(sessionId, {
   }
 });
 
-// Term: derived definition — first projection of S1
 const { state, diagnostics } = tool.addOrUpdateConstituenta(sessionId, {
   draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
 });
 
 console.log(state.analysis.success, diagnostics.length);
+```
 
-// Scratch check
-tool.analyzeExpression(sessionId, {
-  expression: '(',
-  cstType: CstType.TERM
-}); // success: false, syntax diagnostics
+## Analyze Before Upsert
 
-// Set base binding and evaluate a scratch arithmetic term
-tool.setConstituentaValue(sessionId, {
-  target: 1,
-  value: { 0: 'zero', 1: 'one' }
-});
-const evalResult = tool.evaluateExpression(sessionId, {
-  expression: '1+2',
+Use scratch analysis when syntax or `cstType` is uncertain.
+
+```ts
+const analysis = tool.analyzeExpression(sessionId, {
+  expression: 'Pr1(S1)',
   cstType: CstType.TERM
 });
-console.log(evalResult.success, evalResult.value); // true, 3
+
+if (!analysis.success) {
+  console.log(analysis.diagnostics.map(({ code, from, to }) => ({ code, from, to })));
+}
 ```
 
-## Wrapper client
+Fix the reported `from` / `to` range, then re-run analysis. Do not retry unchanged input.
+
+## Wrapper Client
+
+Use the wrapper when the agent talks to a separate `rstool-wrapper` process.
 
 ```ts
 import { CstType } from '@rsconcept/rstool';
@@ -69,29 +62,13 @@ const client = new RSToolWrapperClient();
 await client.waitUntilReady();
 
 const { sessionId } = await client.call<{ sessionId: string }>('createSession');
+
 await client.call('addOrUpdateConstituenta', {
   sessionId,
   input: {
     draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
   }
 });
-await client.call('addOrUpdateConstituenta', {
-  sessionId,
-  input: {
-    draft: {
-      id: 2,
-      alias: 'S1',
-      cstType: CstType.STRUCTURED,
-      definitionFormal: 'ℬ(X1×X1)'
-    }
-  }
-});
-await client.call('addOrUpdateConstituenta', {
-  sessionId,
-  input: {
-    draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
-  }
-});
 
 const diagnostics = await client.call('listDiagnostics', { sessionId });
 console.log(diagnostics);
@@ -99,34 +76,48 @@ console.log(diagnostics);
 await client.close();
 ```
 
-## Manual stdio
+Manual stdio is one JSON request per line:
 
-Start wrapper in one terminal:
-
-```bash
-npx rstool-wrapper
+```jsonl
+{ "id": "1", "method": "createSession", "params": {} }
+{ "id": "2", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 1, "alias": "X1", "cstType": "basic", "definitionFormal": "" } } } }
 ```
 
-Paste one JSON request per line after the ready line appears:
+## Export / Import
 
-```json
-{ "id": "1", "method": "createSession", "params": {} }
+```ts
+const payload = tool.exportSession(sessionId);
+const restored = tool.importSession(payload);
 ```
 
-Use the returned `sessionId` in subsequent lines:
+Export includes session state and model values.
 
-```json
-{ "id": "2", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 1, "alias": "X1", "cstType": "basic", "definitionFormal": "" } } } }
-{ "id": "3", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 2, "alias": "S1", "cstType": "structure", "definitionFormal": "ℬ(X1×X1)" } } } }
-{ "id": "4", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 3, "alias": "D1", "cstType": "term", "definitionFormal": "Pr1(S1)" } } } }
-{ "id": "5", "method": "listDiagnostics", "params": { "sessionId": "..." } }
+## Evaluation
+
+```ts
+tool.setConstituentaValue(sessionId, {
+  target: 1,
+  value: { 0: 'zero', 1: 'one' }
+});
+
+const scratch = tool.evaluateExpression(sessionId, {
+  expression: '1+2',
+  cstType: CstType.TERM
+});
+
+console.log(scratch.success, scratch.value); // true, 3
 ```
 
-## Export a small RSForm session
+For stored definitions, set values for `basic`, `constant`, and `structure`, then call `evaluateConstituenta` or `recalculateModel`.
+
+## Semantic Smoke Test
+
+When syntax is valid but meaning is uncertain, build a tiny model and assert the value.
 
 ```ts
-import { CstType, RSToolAgent } from '@rsconcept/rstool';
+import { CstType, EvalStatus, RSToolAgent } from '@rsconcept/rstool';
 
+const TUPLE_ID = -111;
 const tool = new RSToolAgent();
 const { sessionId } = tool.createSession();
 
@@ -134,62 +125,48 @@ tool.addOrUpdateConstituenta(sessionId, {
   draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
 });
 tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 2, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' }
-});
-tool.addOrUpdateConstituenta(sessionId, {
-  draft: {
-    id: 3,
-    alias: 'S1',
-    cstType: CstType.STRUCTURED,
-    definitionFormal: 'ℬ(X1×X1)',
-    convention: 'Pairs (parent, child) over X1.'
-  }
-});
-tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 4, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
+  draft: { id: 2, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' }
 });
 tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 5, alias: 'A1', cstType: CstType.AXIOM, definitionFormal: '1=1' }
+  draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
 });
 
-const payload = tool.exportSession(sessionId);
-console.log(payload);
-```
-
-## Model and evaluation
-
-Full kinship modeling (`S1` values as tuples, `Pr1(S1)`, …): `examples/build-kinship-rsmodel.ts`.
-
-Minimal evaluation after bindings:
-
-```ts
-tool.setConstituentaValue(sessionId, {
-  target: 1,
-  value: { 0: 'zero', 1: 'one' }
+tool.setConstituentaValues(sessionId, {
+  items: [
+    { target: 1, value: { 0: 'ann', 1: 'bob', 2: 'cat' } },
+    {
+      target: 2,
+      value: [
+        [TUPLE_ID, 0, 1],
+        [TUPLE_ID, 0, 2]
+      ]
+    }
+  ]
 });
 
-const evaluated = tool.evaluateConstituenta(sessionId, {
-  constituentId: 4 // D1 = Pr1(S1); needs S1 interpreted — see kinship example
-});
-console.log(evaluated.success, evaluated.value);
+const result = tool.evaluateConstituenta(sessionId, { constituentId: 3 });
+
+if (!result.success || result.status !== EvalStatus.HAS_DATA || JSON.stringify(result.value) !== '[0]') {
+  throw new Error(`Expected Pr1(S1) to select the first coordinate; got ${JSON.stringify(result)}`);
+}
 ```
 
+Use this pattern for tests that protect important definitions. Full kinship model: `../../examples/build-kinship-rsmodel.ts`. More notes: `../../docs/MODEL-TESTING.md`.
+
 ## Common mistakes
 
-| Mistake                                            | Symptom                                          |
-| -------------------------------------------------- | ------------------------------------------------ |
-| `definitionFormal: 'Z'` on `X1` (`basic`)          | `0x8862` definitionNotAllowed                    |
-| `D1` uses `D2` before `D2` exists                  | globalNotTyped / undeclared global               |
-| `analyzeExpression` with wrong `cstType`           | Role-specific semantic errors                    |
-| Non-empty formal on `C1` (`constant`)              | Same as basic — definition not allowed           |
-| `term` with `X1×X1` when modeling a **relation**   | Full Cartesian product instead of typed pairs in `S#` |
-| `structure` with `Pr1(S1)` instead of a grade      | Wrong role — projections belong on `term` / `F#`   |
-| `setConstituentaValue` on inferrable `D1` (`term`) | Error: inferrable and cannot be set directly     |
-| Evaluating before base binding set                 | May fail or return empty depending on expression |
+- `definitionFormal: 'Z'` on `basic` / `constant` → `definitionNotAllowed`.
+- `D1` uses `D2` before `D2` exists → global not typed / undeclared.
+- Wrong `cstType` in `analyzeExpression` → role-specific errors.
+- `term` with `X1×X1` for a relation → full Cartesian product, not relation typification.
+- `structure` with `Pr1(S1)` → wrong role; projections belong on `term` / `function`.
+- `setConstituentaValue` on `term`, `axiom`, or `statement` → cannot set computed constituents directly.
+- Evaluation before base bindings → missing value, empty result, or evaluation failure.
 
-## Fixing a syntax error
+## Fix Syntax
 
 1. `analyzeExpression` with the broken fragment and correct `cstType`.
-2. Read first diagnostic `{ from, to, code }`.
-3. Edit substring of `definitionFormal` at those offsets.
-4. `addOrUpdateConstituenta` again with the same `id` / `alias`.
+2. Read `{ code, from, to, params }`.
+3. Edit the substring of `definitionFormal` at those offsets.
+4. Re-run analysis.
+5. Upsert with the same `id` / `alias`.