@rsconcept/rstool 1.3.0 → 1.4.1

package/skills/rstool-helper/GUIDE.md

@@ -84,12 +84,13 @@ kind `auto` (default) определит `portal-details` или `portal-schema`
 
 Когда `analysis.success === false` или `listDiagnostics` не пуст. Коды и типичные ошибки — [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
 
-1. Запусти `analyzeExpression` (черновик без сохранения).
-2. Прочитай `code`, `from`, `to`, `params` в `analysis.diagnostics` или через `listDiagnostics`.
-3. Сопоставь `code` с исправлением в [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
-4. Исправь именно диапазон в `definitionFormal`.
-5. Не повторяй вызов без изменения ввода.
-6. После успеха — ещё один `applySchemaPatch` с исправленным элементом.
+1. Вызови `listDiagnostics()` — смотри `kind`: `expression` (формула), `schema` (омонимы, дубликаты, термин/конвенция), `model` (интерпретация).
+2. Для черновика формулы — `analyzeExpression` (без сохранения).
+3. Прочитай `name`, `severity`, `alias`, `from`, `to`, `params` в `analysis.diagnostics` или через `listDiagnostics({ kind })`.
+4. Сопоставь `name` (или `code`) с исправлением в [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
+5. Исправь именно диапазон в `definitionFormal` (expression) или метаданные/данные модели (schema/model).
+6. Не повторяй вызов без изменения ввода.
+7. После успеха — ещё один `applySchemaPatch` / `setModelValues` с исправлением.
 
 ### Проверка на маленькой КМ
 

package/skills/rstool-helper/REFERENCE.md

@@ -3,30 +3,30 @@
 ## Контракт rstool
 
 - Пакет: `@rsconcept/rstool`
-- Версия контракта: `2.0.0` (`CONTRACT_VERSION`)
+- Версия контракта: `3.0.0` (`CONTRACT_VERSION`)
 - Основной класс: `RSToolAgent`
 - Публичные импорты: `@rsconcept/rstool` и `@rsconcept/rstool/wrapper`
 
 ### Методы 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 (`kind` см. ниже)     |
-| `setModelValues({ set?, clear? }, sessionId?)` | Значения модели (async — нужен `await`)      |
-| `getModelState(sessionId?)`                    | Состояние интерпретации                      |
-| `evaluate(input, sessionId?)`                  | Scratch или конституента                     |
-| `recalculateModel(sessionId?)`                 | Пересчёт                                     |
+| Метод                                          | Назначение                                                         |
+| ---------------------------------------------- | ------------------------------------------------------------------ |
+| `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`
 

package/src/index.ts

@@ -2,14 +2,16 @@
  * Public API for `@rsconcept/rstool`.
  *
  * Primary entry points: {@link RSToolAgent} (in-process) and {@link RSToolWrapperClient}
- * (stdio child process). Types describe the v2 agent contract.
+ * (stdio child process). Types describe the v3 agent contract.
  */
-export { toPublicAnalysis, toPublicError, type DomainAnalysisLike, type DomainErrorLike } from './mappers/types';
+export { toDiagnostic, toPublicAnalysis, type DomainAnalysisLike, type DomainErrorLike } from './mappers/types';
 export {
   CONTRACT_VERSION,
   CstType,
+  DiagnosticKind,
   EvalStatus,
   RSErrorCode,
+  RSDiagnosticCode,
   RSToolAgent,
   ValueClass,
   type AgentConstituentaPatch,
@@ -20,7 +22,9 @@ export {
   type BasicBinding,
   type ConstituentaDraft,
   type ConstituentaState,
-  type DiagnosticRecord,
+  type CstDiagnostic,
+  type Diagnostic,
+  type DiagnosticSeverity,
   type EvaluateInput,
   type EvaluationResult,
   type ExportFormat,
@@ -40,7 +44,6 @@ export {
   type RecalculateModelResult,
   type RSToolAgentContract,
   type RSToolAgentOptions,
-  type RSToolErrorDescription,
   type RSToolValue,
   type SessionHandle,
   type SessionModelState,

package/src/mappers/diagnostic-assembly.ts

@@ -0,0 +1,96 @@
+import {
+  type Constituenta,
+  type CstDiagnostic,
+  DiagnosticKind,
+  modelStatusCstDiagnostic,
+  RSDiagnosticCode
+} from '@rsconcept/domain/library';
+import { EvalStatus } from '@rsconcept/domain/library/rsmodel';
+import { isCritical, RSErrorCode, type RSErrorDescription } from '@rsconcept/domain/rslang/error';
+
+export { DiagnosticKind, RSDiagnosticCode };
+
+/** Severity of a {@link Diagnostic}. */
+export type DiagnosticSeverity = 'error' | 'warning';
+
+/** Agent-facing diagnostic with redundant fields for autonomous repair. */
+export interface Diagnostic extends CstDiagnostic {
+  name: string;
+  severity: DiagnosticSeverity;
+  constituentId?: number;
+  alias?: string;
+  expression: string;
+  from: number;
+  to: number;
+}
+
+/** Context for attributing a {@link Diagnostic} to a constituent. */
+export interface DiagnosticTarget {
+  constituentId?: number;
+  alias?: string;
+}
+
+const DIAGNOSTIC_NAMES: ReadonlyMap<number, string> = new Map([
+  ...Object.entries(RSErrorCode).map(([name, code]) => [code, name] as const),
+  ...Object.entries(RSDiagnosticCode).map(([name, code]) => [code, name] as const)
+]);
+
+export function getDiagnosticName(code: number): string {
+  return DIAGNOSTIC_NAMES.get(code) ?? `0x${code.toString(16).toUpperCase()}`;
+}
+
+export function getDiagnosticSeverity(code: number): DiagnosticSeverity {
+  return isCritical(code as RSErrorCode) ? 'error' : 'warning';
+}
+
+export function expandCstDiagnostic(cst: Constituenta, diagnostic: CstDiagnostic): Diagnostic {
+  const expression = expressionForCstDiagnostic(cst, diagnostic);
+  return {
+    ...diagnostic,
+    name: getDiagnosticName(diagnostic.code),
+    severity: getDiagnosticSeverity(diagnostic.code),
+    constituentId: cst.id,
+    alias: cst.alias,
+    expression,
+    from: 0,
+    to: diagnostic.kind === DiagnosticKind.MODEL ? 0 : Math.max(expression.length, 1)
+  };
+}
+
+export function expressionDiagnostic(
+  error: RSErrorDescription,
+  expression: string,
+  target?: DiagnosticTarget
+): Diagnostic {
+  return {
+    kind: DiagnosticKind.EXPRESSION,
+    code: error.code,
+    name: getDiagnosticName(error.code),
+    severity: getDiagnosticSeverity(error.code),
+    constituentId: target?.constituentId,
+    alias: target?.alias,
+    expression,
+    from: error.from,
+    to: error.to,
+    ...(error.params ? { params: error.params } : {})
+  };
+}
+
+export function modelStatusDiagnostic(status: EvalStatus, cst: Constituenta): Diagnostic | null {
+  const base = modelStatusCstDiagnostic(status, cst.cst_type);
+  return base ? expandCstDiagnostic(cst, base) : null;
+}
+
+function expressionForCstDiagnostic(cst: Constituenta, diagnostic: CstDiagnostic): string {
+  switch (diagnostic.code) {
+    case RSDiagnosticCode.schemaHomonym:
+    case RSDiagnosticCode.schemaMissingTerm:
+      return cst.term_resolved;
+    case RSDiagnosticCode.schemaMissingConvention:
+      return cst.convention;
+    case RSDiagnosticCode.schemaTypeMismatch:
+      return cst.typification_manual;
+    default:
+      return cst.definition_formal;
+  }
+}

package/src/mappers/diagnostics-collector.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest';
+
+import { CstType, RSErrorCode, RSDiagnosticCode, type SessionState, ValueClass } from '../models';
+import { expressionDiagnostic } from './diagnostic-assembly';
+import { collectModelDiagnostics, collectSchemaDiagnostics, collectSessionDiagnostics } from './diagnostics-collector';
+
+function buildFixtureSession(): SessionState {
+  return {
+    sessionId: 'test',
+    alias: '',
+    title: '',
+    comment: '',
+    createdAt: '',
+    updatedAt: '',
+    revisions: [],
+    model: { items: [] },
+    items: [
+      {
+        id: 1,
+        alias: 'X1',
+        cstType: CstType.BASE,
+        definitionFormal: 'Z',
+        term: '',
+        definitionText: '',
+        convention: '',
+        analysis: {
+          success: false,
+          type: null,
+          valueClass: null,
+          diagnostics: [
+            expressionDiagnostic(
+              { code: RSErrorCode.definitionNotAllowed, from: 0, to: 1, params: [CstType.BASE, 'X1'] },
+              'Z',
+              { constituentId: 1, alias: 'X1' }
+            )
+          ]
+        }
+      },
+      {
+        id: 2,
+        alias: 'X2',
+        cstType: CstType.BASE,
+        definitionFormal: '',
+        term: 'person',
+        definitionText: '',
+        convention: 'people',
+        analysis: { success: true, type: {}, valueClass: ValueClass.VALUE, diagnostics: [] }
+      },
+      {
+        id: 3,
+        alias: 'X3',
+        cstType: CstType.BASE,
+        definitionFormal: '',
+        term: 'Person',
+        definitionText: '',
+        convention: 'other',
+        analysis: { success: true, type: {}, valueClass: ValueClass.VALUE, diagnostics: [] }
+      }
+    ]
+  };
+}
+
+describe('collectSchemaDiagnostics', () => {
+  it('collects expression and schema diagnostics without model issues', () => {
+    const records = collectSchemaDiagnostics(buildFixtureSession());
+
+    expect(records.some(record => record.kind === 'expression')).toBe(true);
+    expect(records.some(record => record.code === RSDiagnosticCode.schemaHomonym)).toBe(true);
+    expect(records.some(record => record.code === RSDiagnosticCode.schemaMissingTerm)).toBe(true);
+    expect(records.some(record => record.code === RSDiagnosticCode.modelEmpty)).toBe(false);
+    expect(records.every(record => record.name.length > 0)).toBe(true);
+  });
+});
+
+describe('collectModelDiagnostics', () => {
+  it('collects model diagnostics for empty basic sets', () => {
+    const records = collectModelDiagnostics(buildFixtureSession());
+
+    expect(records.some(record => record.code === RSDiagnosticCode.modelEmpty)).toBe(true);
+    expect(records.every(record => record.kind === 'model')).toBe(true);
+  });
+});
+
+describe('collectSessionDiagnostics', () => {
+  it('merges schema and model diagnostics', () => {
+    const records = collectSessionDiagnostics(buildFixtureSession());
+
+    expect(records.some(record => record.kind === 'expression')).toBe(true);
+    expect(records.some(record => record.code === RSDiagnosticCode.schemaHomonym)).toBe(true);
+    expect(records.some(record => record.code === RSDiagnosticCode.modelEmpty)).toBe(true);
+  });
+});

package/src/mappers/diagnostics-collector.ts

@@ -0,0 +1,77 @@
+import { isModelIssue } from '@rsconcept/domain/library/rsmodel-api';
+
+import { type SessionState } from '../models';
+import {
+  DiagnosticKind,
+  expandCstDiagnostic,
+  modelStatusDiagnostic,
+  type Diagnostic
+} from './diagnostic-assembly';
+import { ModelAdapter } from './model-adapter';
+import { enrichSessionConstituents } from './rsform-builder';
+import { toDiagnostic } from './types';
+
+const modelAdapter = new ModelAdapter();
+
+/** Collect expression and schema diagnostics for a session. */
+export function collectSchemaDiagnostics(session: SessionState): Diagnostic[] {
+  const records: Diagnostic[] = [];
+
+  for (const item of session.items) {
+    for (const diagnostic of item.analysis.diagnostics) {
+      const base = diagnostic.name
+        ? diagnostic
+        : toDiagnostic(diagnostic, item.definitionFormal, {
+            constituentId: item.id,
+            alias: item.alias
+          });
+      records.push({
+        ...base,
+        kind: DiagnosticKind.EXPRESSION,
+        constituentId: base.constituentId ?? item.id,
+        alias: base.alias ?? item.alias
+      });
+    }
+  }
+
+  const enriched = enrichSessionConstituents(session);
+  for (const { cst } of enriched) {
+    for (const diagnostic of cst.diagnostics) {
+      if (diagnostic.kind !== DiagnosticKind.SCHEMA) {
+        continue;
+      }
+      records.push(expandCstDiagnostic(cst, diagnostic));
+    }
+  }
+
+  return records;
+}
+
+/** Collect model diagnostics for a session (requires schema items). */
+export function collectModelDiagnostics(session: SessionState): Diagnostic[] {
+  if (session.items.length === 0) {
+    return [];
+  }
+
+  const records: Diagnostic[] = [];
+  const enriched = enrichSessionConstituents(session);
+  const schema = enriched.map(entry => entry.cst);
+  const engine = modelAdapter.createEngine(session);
+  engine.recalculateAll();
+  for (const cst of schema) {
+    if (!isModelIssue(engine, cst)) {
+      continue;
+    }
+    const diagnostic = modelStatusDiagnostic(engine.getCstStatus(cst.id), cst);
+    if (diagnostic) {
+      records.push(diagnostic);
+    }
+  }
+
+  return records;
+}
+
+/** Collect expression, schema, and model diagnostics for a session. */
+export function collectSessionDiagnostics(session: SessionState): Diagnostic[] {
+  return [...collectSchemaDiagnostics(session), ...collectModelDiagnostics(session)];
+}

package/src/mappers/model-adapter.ts

@@ -1,8 +1,7 @@
-import { Graph } from '@rsconcept/domain/graph/graph';
-import { extractGlobals } from '@rsconcept/domain/rslang/api';
-import { type ExpressionType, RSLangAnalyzer, type Value, type ValueClass } from '@rsconcept/domain/rslang';
+import { DiagnosticKind, expressionDiagnostic } from './diagnostic-assembly';
+import { type RSErrorDescription, type Value } from '@rsconcept/domain/rslang';
 import { isBaseSet } from '@rsconcept/domain/library/rsform-api';
-import { type Constituenta, CstType, type RSForm } from '@rsconcept/domain/library/rsform';
+import { CstType, type RSForm } from '@rsconcept/domain/library/rsform';
 import { RSEngine, type RSEngineServices } from '@rsconcept/domain/library/rsengine';
 import { type BasicBinding, EvalStatus, type RSModel } from '@rsconcept/domain/library/rsmodel';
 import {
@@ -14,14 +13,13 @@ import {
 } from '@rsconcept/domain/library/rsmodel-api';
 
 import {
-  type ConstituentaState,
   type EvaluationResult,
   type RecalculateModelResult,
   type SessionModelState,
   type SessionState,
   type SetConstituentaValueInput
 } from '../models';
-import { toPublicError } from './types';
+import { buildRSFormFromSession } from './rsform-builder';
 
 const SESSION_MODEL_ID = 0;
 
@@ -73,7 +71,14 @@ export class ModelAdapter {
           ? EvalStatus.EVAL_FAIL
           : EvalStatus.EMPTY
         : EvalStatus.HAS_DATA;
-    return toPublicEvaluationResult(result.value, result.errors, result.iterations, result.cacheHits, status);
+    return toPublicEvaluationResult(
+      result.value,
+      result.errors,
+      result.iterations,
+      result.cacheHits,
+      status,
+      expression
+    );
   }
 
   public evaluateConstituenta(session: SessionState, constituentId: number): EvaluationResult {
@@ -84,7 +89,15 @@ export class ModelAdapter {
     const engine = this.createEngine(session);
     const result = engine.calculateCst(constituentId);
     const status = engine.getCstStatus(constituentId);
-    return toPublicEvaluationResult(result.value, result.errors, result.iterations, result.cacheHits, status);
+    return toPublicEvaluationResult(
+      result.value,
+      result.errors,
+      result.iterations,
+      result.cacheHits,
+      status,
+      cst.definitionFormal,
+      { constituentId: cst.id, alias: cst.alias }
+    );
   }
 
   public recalculateModel(session: SessionState): RecalculateModelResult {
@@ -155,55 +168,6 @@ function createInMemoryServices(session: SessionState): RSEngineServices {
   };
 }
 
-function buildRSFormFromSession(session: SessionState): RSForm {
-  const graph = new Graph<number>();
-  const cstByAlias = new Map<string, Constituenta>();
-  const cstByID = new Map<number, Constituenta>();
-  const analyzer = new RSLangAnalyzer();
-
-  const items = session.items.map(item => {
-    const cst = toFrontendConstituenta(item);
-    cstByAlias.set(cst.alias, cst);
-    cstByID.set(cst.id, cst);
-    graph.addNode(cst.id);
-    if (item.cstType === CstType.BASE) {
-      analyzer.addBase(cst.alias);
-    }
-    if (cst.effectiveType) {
-      analyzer.setGlobal(cst.alias, cst.effectiveType, cst.analysis.valueClass as ValueClass | null);
-    }
-    return cst;
-  });
-
-  for (const cst of items) {
-    for (const alias of extractGlobals(cst.definition_formal)) {
-      const source = cstByAlias.get(alias);
-      if (source) {
-        graph.addEdge(source.id, cst.id);
-      }
-    }
-  }
-
-  return {
-    id: 0,
-    items,
-    cstByAlias,
-    cstByID,
-    graph,
-    analyzer,
-    inheritance: [],
-    attribution: [],
-    attribution_graph: graph.clone(),
-    oss: [],
-    models: [],
-    editors: [],
-    versions: [],
-    is_produced: false,
-    is_attributive: false,
-    version: 'latest'
-  } as unknown as RSForm;
-}
-
 function buildRSModelFromSession(session: SessionState): RSModel {
   return {
     id: SESSION_MODEL_ID,
@@ -217,54 +181,19 @@ function buildRSModelFromSession(session: SessionState): RSModel {
   } as unknown as RSModel;
 }
 
-function toFrontendConstituenta(item: ConstituentaState): Constituenta {
-  const effectiveType = (item.analysis.type ?? null) as ExpressionType | null;
-  return {
-    id: item.id,
-    alias: item.alias,
-    cst_type: item.cstType,
-    definition_formal: item.definitionFormal,
-    definition_raw: item.definitionFormal,
-    definition_resolved: item.definitionFormal,
-    term_raw: item.term,
-    term_resolved: item.term,
-    term_forms: [],
-    convention: item.convention,
-    typification_manual: '',
-    value_is_property: false,
-    crucial: false,
-    attributes: [],
-    homonyms: [],
-    formalDuplicates: [],
-    analysis: {
-      success: item.analysis.success,
-      type: effectiveType,
-      valueClass: item.analysis.valueClass
-    },
-    effectiveType,
-    is_type_mismatch: false,
-    schema: 0,
-    cst_class: 'derived',
-    status: item.analysis.success ? 'verified' : 'incorrect',
-    is_template: false,
-    is_simple_expression: true,
-    parent_schema_index: 0,
-    parent_schema: null,
-    is_inherited: false,
-    has_inherited_children: false,
-    spawn: [],
-    spawn_alias: []
-  } as unknown as Constituenta;
-}
-
 function toPublicEvaluationResult(
   value: Value | null,
-  errors: { code: number; from: number; to: number; params?: readonly string[] }[],
+  errors: RSErrorDescription[],
   iterations: number,
   cacheHits: number,
-  status: EvalStatus
+  status: EvalStatus,
+  expression: string,
+  target?: { constituentId?: number; alias?: string }
 ): EvaluationResult {
-  const diagnostics = errors.map(toPublicError);
+  const diagnostics = errors.map(error => ({
+    ...expressionDiagnostic(error, expression, target),
+    kind: DiagnosticKind.MODEL
+  }));
   return {
     success: diagnostics.length === 0 && value !== null,
     value: value as EvaluationResult['value'],

package/src/mappers/rsform-builder.ts

@@ -0,0 +1,127 @@
+import { Graph } from '@rsconcept/domain/graph/graph';
+import { extractGlobals } from '@rsconcept/domain/rslang/api';
+import { type ExpressionType, RSLangAnalyzer, type ValueClass } from '@rsconcept/domain/rslang';
+import { assignSchemaDiagnostics } from '@rsconcept/domain/library';
+import { isBasicConcept, isLogical, normalizeExpression } from '@rsconcept/domain/library/rsform-api';
+import { type Constituenta, CstType, type RSForm } from '@rsconcept/domain/library/rsform';
+
+import { type ConstituentaState, type SessionState } from '../models';
+
+export interface EnrichedConstituenta {
+  item: ConstituentaState;
+  cst: Constituenta;
+}
+
+/** Build a domain {@link RSForm} view from session state (same shape as Portal loader output). */
+export function buildRSFormFromSession(session: SessionState): RSForm {
+  const graph = new Graph<number>();
+  const cstByAlias = new Map<string, Constituenta>();
+  const cstByID = new Map<number, Constituenta>();
+  const analyzer = new RSLangAnalyzer();
+
+  const items = session.items.map(item => {
+    const cst = toFrontendConstituenta(item);
+    cstByAlias.set(cst.alias, cst);
+    cstByID.set(cst.id, cst);
+    graph.addNode(cst.id);
+    if (item.cstType === CstType.BASE) {
+      analyzer.addBase(cst.alias);
+    }
+    if (cst.effectiveType) {
+      analyzer.setGlobal(cst.alias, cst.effectiveType, cst.analysis.valueClass as ValueClass | null);
+    }
+    return cst;
+  });
+
+  for (const cst of items) {
+    for (const alias of extractGlobals(cst.definition_formal)) {
+      const source = cstByAlias.get(alias);
+      if (source) {
+        graph.addEdge(source.id, cst.id);
+      }
+    }
+  }
+
+  return {
+    id: 0,
+    items,
+    cstByAlias,
+    cstByID,
+    graph,
+    analyzer,
+    inheritance: [],
+    attribution: [],
+    attribution_graph: graph.clone(),
+    oss: [],
+    models: [],
+    editors: [],
+    versions: [],
+    is_produced: false,
+    is_attributive: false,
+    version: 'latest'
+  } as unknown as RSForm;
+}
+
+/** Enrich session constituents with Portal-style schema metadata used for diagnostics. */
+export function enrichSessionConstituents(session: SessionState): EnrichedConstituenta[] {
+  const schema = buildRSFormFromSession(session);
+  const normalizedDefinitions = new Map<number, string>();
+  const resolveAlias = (id: number) => schema.cstByID.get(id)?.alias ?? String(id);
+
+  for (const item of session.items) {
+    const normalized = normalizeExpression(item.definitionFormal, item.cstType);
+    if (normalized) {
+      normalizedDefinitions.set(item.id, normalized);
+    }
+  }
+
+  assignSchemaDiagnostics(schema.items, resolveAlias, normalizedDefinitions);
+
+  return session.items.map(item => ({
+    item,
+    cst: schema.cstByID.get(item.id)!
+  }));
+}
+
+function toFrontendConstituenta(item: ConstituentaState): Constituenta {
+  const effectiveType = (item.analysis.type ?? null) as ExpressionType | null;
+  return {
+    id: item.id,
+    alias: item.alias,
+    cst_type: item.cstType,
+    definition_formal: item.definitionFormal,
+    definition_raw: item.definitionFormal,
+    definition_resolved: item.definitionFormal,
+    term_raw: item.term,
+    term_resolved: item.term,
+    term_forms: [],
+    convention: item.convention,
+    typification_manual: '',
+    value_is_property: false,
+    crucial: false,
+    attributes: [],
+    diagnostics: [],
+    analysis: {
+      success: item.analysis.success,
+      type: effectiveType,
+      valueClass: item.analysis.valueClass
+    },
+    effectiveType,
+    is_type_mismatch: false,
+    schema: 0,
+    cst_class: 'derived',
+    status: item.analysis.success ? 'verified' : 'incorrect',
+    is_template: false,
+    is_simple_expression: true,
+    parent_schema_index: 0,
+    parent_schema: null,
+    is_inherited: false,
+    has_inherited_children: false,
+    spawn: [],
+    spawn_alias: []
+  } as unknown as Constituenta;
+}
+
+export function needsBasicMetadata(item: ConstituentaState): boolean {
+  return isBasicConcept(item.cstType) && !isLogical(item.cstType);
+}