@rsconcept/rstool 1.2.2 → 1.4.0

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);
+}

package/src/mappers/schema-adapter.ts

@@ -1,4 +1,6 @@
+import { expressionDiagnostic } from './diagnostic-assembly';
 import { RSLangAnalyzer, type AnalysisFull, type ValueClass } from '@rsconcept/domain/rslang';
+import { type RSErrorDescription } from '@rsconcept/domain/rslang/error';
 import { getAnalysisFor } from '@rsconcept/domain/library/rsform-api';
 import { CstType, type RSForm } from '@rsconcept/domain/library/rsform';
 
@@ -6,33 +8,35 @@ import {
   type AnalysisResult,
   type ConstituentaDraft,
   type ConstituentaState,
-  type DiagnosticRecord,
+  type Diagnostic,
   type SessionState
 } from '../models';
-import { toPublicAnalysis, toPublicError } from './types';
+import { toPublicAnalysis } from './types';
 
 export class SchemaAdapter {
   public analyzeAgainstSession(
     session: SessionState,
     draft: ConstituentaDraft
-  ): { result: AnalysisResult; diagnostics: DiagnosticRecord[] } {
+  ): { 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 result = toPublicAnalysis({
-      success: analysis.success,
-      type: analysis.type as Record<string, unknown> | null,
-      valueClass: analysis.valueClass,
-      errors: analysis.errors
-    });
+    const target = { constituentId: draft.id, alias: draft.alias };
+    const result = toPublicAnalysis(
+      {
+        success: analysis.success,
+        type: analysis.type as Record<string, unknown> | null,
+        valueClass: analysis.valueClass,
+        errors: analysis.errors
+      },
+      draft.definitionFormal,
+      target
+    );
     return {
       result,
-      diagnostics: analysis.errors.map(error => ({
-        sessionId: session.sessionId,
-        constituentId: draft.id,
-        expression: draft.definitionFormal,
-        error: toPublicError(error)
-      }))
+      diagnostics: analysis.errors.map(error =>
+        expressionDiagnostic(error as RSErrorDescription, draft.definitionFormal, target)
+      )
     };
   }
 

package/src/mappers/types.ts

@@ -1,8 +1,9 @@
-import { type ValueClass } from '@rsconcept/domain/rslang';
+import { DiagnosticKind, type DiagnosticTarget, expressionDiagnostic } from './diagnostic-assembly';
+import { type RSErrorDescription, type ValueClass } from '@rsconcept/domain/rslang';
 
-import { type AnalysisResult, type RSToolErrorDescription } from '../models';
+import { type AnalysisResult, type Diagnostic } from '../models';
 
-/** Minimal domain error shape before mapping to {@link RSToolErrorDescription}. */
+/** Minimal domain error shape before mapping to {@link Diagnostic}. */
 export interface DomainErrorLike {
   code: number;
   from: number;
@@ -19,21 +20,20 @@ export interface DomainAnalysisLike {
 }
 
 /** Map a domain parser/semantic error to the public diagnostic shape. */
-export function toPublicError(error: DomainErrorLike): RSToolErrorDescription {
-  return {
-    code: error.code,
-    from: error.from,
-    to: error.to,
-    params: error.params
-  };
+export function toDiagnostic(error: DomainErrorLike, expression: string, target?: DiagnosticTarget): Diagnostic {
+  return expressionDiagnostic(error as RSErrorDescription, expression, target);
 }
 
 /** Map a domain analysis result to the public {@link AnalysisResult} shape. */
-export function toPublicAnalysis(analysis: DomainAnalysisLike): AnalysisResult {
+export function toPublicAnalysis(
+  analysis: DomainAnalysisLike,
+  expression: string,
+  target?: DiagnosticTarget
+): AnalysisResult {
   return {
     success: analysis.success,
     type: analysis.type,
     valueClass: analysis.valueClass,
-    diagnostics: analysis.errors.map(toPublicError)
+    diagnostics: analysis.errors.map(error => expressionDiagnostic(error as RSErrorDescription, expression, target))
   };
 }

package/src/models/agent-workflow.ts

@@ -1,6 +1,6 @@
 import { type CstType } from './common';
 import { type ApplyConstituentsMode, type ApplyConstituentsResult, type ConstituentaDraft } from './constituenta';
-import { type DiagnosticRecord } from './diagnostic';
+import { type Diagnostic } from './diagnostic';
 import { type SessionHandle, type SessionRevision, type SessionState } from './session';
 
 /** Level of detail returned by {@link RSToolAgent.getSessionState}. */
@@ -54,7 +54,7 @@ export interface SessionSummary {
   modelItemCount: number;
   diagnosticsCount: number;
   items: SessionSummaryItem[];
-  diagnostics: DiagnosticRecord[];
+  diagnostics: Diagnostic[];
   lastRevision?: SessionRevision;
 }
 

package/src/models/analysis.ts

@@ -1,4 +1,5 @@
-import { type CstType, type RSToolErrorDescription, type ValueClass } from './common';
+import { type Diagnostic } from './diagnostic';
+import { type CstType, type ValueClass } from './common';
 
 /** Input for {@link RSToolAgent.analyzeExpression}. */
 export interface AnalyzeExpressionInput {
@@ -16,5 +17,5 @@ export interface AnalysisResult {
   /** Inferred RS type AST as a plain object, or `null` on failure. */
   type: Record<string, unknown> | null;
   valueClass: ValueClass | null;
-  diagnostics: RSToolErrorDescription[];
+  diagnostics: Diagnostic[];
 }

package/src/models/common.ts

@@ -10,15 +10,3 @@ 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

@@ -1,6 +1,6 @@
 import { type AnalysisResult } from './analysis';
 import { type CstType } from './common';
-import { type DiagnosticRecord } from './diagnostic';
+import { type Diagnostic } from './diagnostic';
 
 /** Constituent payload before analysis and merge into session state. */
 export interface ConstituentaDraft {
@@ -33,7 +33,7 @@ export interface AddOrUpdateConstituentaInput {
 
 export interface AddOrUpdateConstituentaResult {
   state: ConstituentaState;
-  diagnostics: DiagnosticRecord[];
+  diagnostics: Diagnostic[];
 }
 
 /** How a multi-draft apply handles partial failures. */
@@ -48,6 +48,6 @@ export interface ApplyConstituentsInput {
 export interface ApplyConstituentsResult {
   success: boolean;
   applied: ConstituentaState[];
-  failed: Array<{ draft: ConstituentaDraft; diagnostics: DiagnosticRecord[] }>;
-  diagnostics: DiagnosticRecord[];
+  failed: Array<{ draft: ConstituentaDraft; diagnostics: Diagnostic[] }>;
+  diagnostics: Diagnostic[];
 }

package/src/models/diagnostic.ts

@@ -1,16 +1,21 @@
-import { type RSToolErrorDescription } from './common';
+import { type CstDiagnostic, DiagnosticKind, RSDiagnosticCode } from '@rsconcept/domain/library';
 
-/** 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;
-}
+export {
+  type Diagnostic,
+  type DiagnosticSeverity,
+  type DiagnosticTarget,
+  expandCstDiagnostic,
+  expressionDiagnostic,
+  getDiagnosticName,
+  getDiagnosticSeverity,
+  modelStatusDiagnostic
+} from '../mappers/diagnostic-assembly';
+
+export { type CstDiagnostic, DiagnosticKind, RSDiagnosticCode };
 
 /** Filters for {@link RSToolAgent.listDiagnostics}. */
 export interface ListDiagnosticsFilters {
   constituentId?: number;
+  kind?: DiagnosticKind;
+  severity?: import('../mappers/diagnostic-assembly').DiagnosticSeverity;
 }

package/src/models/evaluation.ts

@@ -1,10 +1,5 @@
-import {
-  type BasicBinding,
-  type CstType,
-  type EvalStatus,
-  type RSToolErrorDescription,
-  type RSToolValue
-} from './common';
+import { type BasicBinding, type CstType, type EvalStatus, type RSToolValue } from './common';
+import { type Diagnostic } from './diagnostic';
 
 export interface EvaluateExpressionInput {
   expression: string;
@@ -32,5 +27,5 @@ export interface EvaluationResult {
   status: EvalStatus;
   iterations: number;
   cacheHits: number;
-  diagnostics: RSToolErrorDescription[];
+  diagnostics: Diagnostic[];
 }

package/src/models/index.ts

@@ -14,11 +14,17 @@ export {
   RSErrorCode,
   ValueClass,
   type BasicBinding,
-  type RSToolErrorDescription,
   type RSToolValue
 } from './common';
 export { type ApplyConstituentsMode, type ConstituentaDraft, type ConstituentaState } from './constituenta';
-export { type DiagnosticRecord, type ListDiagnosticsFilters } from './diagnostic';
+export {
+  type CstDiagnostic,
+  type Diagnostic,
+  DiagnosticKind,
+  type DiagnosticSeverity,
+  type ListDiagnosticsFilters,
+  RSDiagnosticCode
+} from './diagnostic';
 export { type EvaluateInput, type EvaluationResult } from './evaluation';
 export {
   type ExportFormat,

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

@@ -6,7 +6,7 @@ import { describe, expect, it } from 'vitest';
 
 import { TUPLE_ID } from '@rsconcept/domain';
 
-import { CstType, EvalStatus, RSErrorCode, RSToolAgent } from './index';
+import { CstType, EvalStatus, RSErrorCode, RSDiagnosticCode, RSToolAgent } from './index';
 
 function buildSampleForm(tool: RSToolAgent, sessionId: string) {
   tool.applySchemaPatch(
@@ -56,7 +56,7 @@ describe('RSToolAgent', () => {
       session.sessionId
     );
     expect(result.success).toBe(false);
-    expect(result.failed[0]?.diagnostics[0]?.error.code).toBe(RSErrorCode.definitionNotAllowed);
+    expect(result.failed[0]?.diagnostics[0]?.code).toBe(RSErrorCode.definitionNotAllowed);
   });
 
   it('rejects formal definition for basic sets', () => {
@@ -69,7 +69,7 @@ describe('RSToolAgent', () => {
       session.sessionId
     );
     expect(result.success).toBe(false);
-    expect(result.failed[0]?.diagnostics[0]?.error.code).toBe(RSErrorCode.definitionNotAllowed);
+    expect(result.failed[0]?.diagnostics[0]?.code).toBe(RSErrorCode.definitionNotAllowed);
   });
 
   it('returns known analysis for empty base definition', () => {
@@ -474,10 +474,68 @@ describe('RSToolAgent agent ergonomics', () => {
       { mode: 'best_effort', items: [{ alias: 'X1', cstType: CstType.BASE, definitionFormal: 'Z' }] },
       session.sessionId
     );
-    expect(tool.listDiagnostics(undefined, session.sessionId)).toHaveLength(1);
+    const expressionDiags = tool.listDiagnostics({ kind: 'expression' }, session.sessionId);
+    expect(expressionDiags).toHaveLength(1);
+    expect(expressionDiags[0]?.code).toBe(RSErrorCode.definitionNotAllowed);
 
     tool.applySchemaPatch({ items: [{ alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }] }, session.sessionId);
-    expect(tool.listDiagnostics(undefined, session.sessionId)).toHaveLength(0);
+    expect(tool.listDiagnostics({ kind: 'expression' }, session.sessionId)).toHaveLength(0);
+    expect(tool.listDiagnostics({ kind: 'schema' }, session.sessionId).length).toBeGreaterThan(0);
+    expect(tool.listDiagnostics({ kind: 'model' }, session.sessionId).length).toBeGreaterThan(0);
+  });
+
+  it('reports schema homonyms and missing convention', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch(
+      {
+        items: [
+          { alias: 'X1', term: 'person', convention: 'people' },
+          { alias: 'X2', term: 'Person', convention: 'other people' }
+        ]
+      },
+      session.sessionId
+    );
+
+    const homonyms = tool.listDiagnostics({ kind: 'schema' }, session.sessionId);
+    expect(homonyms.some(record => record.code === RSDiagnosticCode.schemaHomonym)).toBe(true);
+    expect(homonyms.filter(record => record.code === RSDiagnosticCode.schemaHomonym)).toHaveLength(2);
+  });
+
+  it('reports formal duplicate definitions', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch(
+      {
+        items: [
+          { alias: 'X1', convention: 'base' },
+          { alias: 'S1', definitionFormal: 'ℬ(X1×X1)', convention: 'pairs' },
+          { alias: 'D1', definitionFormal: 'Pr1(S1)' },
+          { alias: 'D2', definitionFormal: 'Pr1(S1)' }
+        ]
+      },
+      session.sessionId
+    );
+
+    const duplicates = tool
+      .listDiagnostics({ kind: 'schema' }, session.sessionId)
+      .filter(record => record.code === RSDiagnosticCode.schemaFormalDuplicate);
+    expect(duplicates).toHaveLength(2);
+    expect(duplicates[0]?.params?.[0]).toContain('D2');
+  });
+
+  it('reports model diagnostics for empty basic sets', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch(
+      {
+        items: [{ alias: 'X1', convention: 'base', term: 'element' }]
+      },
+      session.sessionId
+    );
+
+    const modelIssues = tool.listDiagnostics({ kind: 'model' }, session.sessionId);
+    expect(modelIssues.some(record => record.code === RSDiagnosticCode.modelEmpty)).toBe(true);
   });
 
   it('does not record analyzeExpression diagnostics by default', () => {
@@ -919,6 +977,9 @@ describe('RSToolAgent modeling semantics', () => {
     const a1 = recalculated.items.find(item => item.alias === 'A1');
     expect(a1?.status).toBe(EvalStatus.AXIOM_FALSE);
     expect(a1?.value).toBe(0);
+
+    const modelIssues = tool.listDiagnostics({ kind: 'model' }, session.sessionId);
+    expect(modelIssues.some(record => record.code === RSDiagnosticCode.modelAxiomFalse)).toBe(true);
   });
 
   it('throws when evaluate input is incomplete', () => {

package/src/models/rstool-agent.ts

@@ -4,6 +4,7 @@ import {
   portalSchemaToDrafts,
   portalSchemaToSessionSeed
 } from '../mappers/portal-adapter';
+import { collectSessionDiagnostics } from '../mappers/diagnostics-collector';
 import { ModelAdapter } from '../mappers/model-adapter';
 import { SchemaAdapter } from '../mappers/schema-adapter';
 import { orderDrafts, reorderSessionItemsByDrafts } from '../session/batch-apply';
@@ -26,7 +27,7 @@ import {
   type ConstituentaDraft,
   type ConstituentaState
 } from './constituenta';
-import { type DiagnosticRecord, type ListDiagnosticsFilters } from './diagnostic';
+import { type Diagnostic, type ListDiagnosticsFilters } from './diagnostic';
 import { type EvaluateInput, type EvaluationResult } from './evaluation';
 import { detectImportKind, parseImportPayload } from './import-detect';
 import { type ExportPortalInput, type ExportPortalResult, type ImportDataKind } from './import-export';
@@ -191,11 +192,11 @@ export class RSToolAgent implements RSToolAgentContract {
       definitionFormal: input.expression
     });
     if (input.recordDiagnostics) {
-      this.sessions.replaceDiagnosticsForConstituent(
-        id,
-        undefined,
-        diagnostics.map(item => ({ ...item, constituentId: undefined }))
-      );
+      const refreshed = collectSessionDiagnostics(envelope.state);
+      this.sessions.setDiagnostics(id, [
+        ...refreshed,
+        ...diagnostics.map(item => ({ ...item, constituentId: undefined }))
+      ]);
     }
     return result;
   }
@@ -263,9 +264,11 @@ export class RSToolAgent implements RSToolAgentContract {
         const model = await this.evaluation.setConstituentaValues(state, { items: input.set });
         state = { ...state, model };
         this.sessions.replaceState(id, state);
+        this.refreshDiagnostics(id);
         return model;
       }
 
+      this.refreshDiagnostics(id);
       return structuredClone(this.sessions.get(id).state.model);
     } catch (error) {
       this.sessions.restore(id, snapshot);
@@ -296,8 +299,11 @@ export class RSToolAgent implements RSToolAgentContract {
 
   /** @inheritdoc */
   public recalculateModel(sessionId?: string): RecalculateModelResult {
-    const envelope = this.sessions.get(this.resolveSessionId(sessionId));
-    return this.evaluation.recalculateModel(envelope.state);
+    const id = this.resolveSessionId(sessionId);
+    const envelope = this.sessions.get(id);
+    const result = this.evaluation.recalculateModel(envelope.state);
+    this.refreshDiagnostics(id);
+    return result;
   }
 
   private addOrUpdateConstituenta(
@@ -308,7 +314,6 @@ export class RSToolAgent implements RSToolAgentContract {
     const envelope = this.sessions.get(id);
     const { result, diagnostics } = this.adapter.analyzeAgainstSession(envelope.state, input.draft);
     const state = this.adapter.mergeStateWithDraft(envelope.state, input.draft, result);
-    this.sessions.replaceDiagnosticsForConstituent(id, input.draft.id, diagnostics);
     return { state, diagnostics };
   }
 
@@ -342,6 +347,7 @@ export class RSToolAgent implements RSToolAgentContract {
     const envelope = this.sessions.get(id);
     reorderSessionItemsByDrafts(envelope.state.items, input.drafts, preBatchItemIds);
     this.sessions.replaceState(id, envelope.state);
+    this.refreshDiagnostics(id);
 
     return {
       success: failed.length === 0,
@@ -418,12 +424,13 @@ export class RSToolAgent implements RSToolAgentContract {
     }
     const data = parsed as {
       state: SessionState;
-      diagnostics?: DiagnosticRecord[];
+      diagnostics?: Diagnostic[];
     };
     const handle = this.sessions.create(normalizeImportedState(data.state), this.contractVersion);
     if (data.diagnostics?.length) {
       this.sessions.setDiagnostics(handle.sessionId, data.diagnostics);
     }
+    this.refreshDiagnostics(handle.sessionId);
     return this.trackSession(handle);
   }
 
@@ -509,4 +516,9 @@ export class RSToolAgent implements RSToolAgentContract {
     this.sessions.saveCurrentSessionId(handle.sessionId);
     return handle;
   }
+
+  private refreshDiagnostics(sessionId: string): void {
+    const envelope = this.sessions.get(sessionId);
+    this.sessions.setDiagnostics(sessionId, collectSessionDiagnostics(envelope.state));
+  }
 }

package/src/models/tool-contract.ts

@@ -5,14 +5,14 @@ import {
   type SessionStateResult
 } from './agent-workflow';
 import { type AnalysisResult, type AnalyzeExpressionInput } from './analysis';
-import { type DiagnosticRecord, type ListDiagnosticsFilters } from './diagnostic';
+import { type Diagnostic, type ListDiagnosticsFilters } from './diagnostic';
 import { type EvaluateInput, type EvaluationResult } from './evaluation';
 import { type ExportPortalInput, type ExportPortalResult, type ImportDataKind } from './import-export';
 import { type RecalculateModelResult, type SessionModelState, type SetModelValuesInput } from './model-value';
 import { type SessionHandle, type SessionRevision, type SessionState } from './session';
 
 /** Agent-visible contract version; bump on breaking API changes. */
-export const CONTRACT_VERSION = '2.0.0';
+export const CONTRACT_VERSION = '3.0.0';
 
 /** Options for constructing an {@link RSToolAgent}. */
 export interface RSToolAgentOptions {
@@ -48,8 +48,8 @@ export interface RSToolAgentContract {
   /** Return session summary (default) or full cloned state when `detail` is `'full'`. */
   getSessionState(detail?: SessionStateDetail, sessionId?: string): SessionStateResult;
 
-  /** List diagnostics for the session, optionally filtered by constituent. */
-  listDiagnostics(filters?: ListDiagnosticsFilters, sessionId?: string): DiagnosticRecord[];
+  /** List diagnostics for the session, optionally filtered by constituent or kind. */
+  listDiagnostics(filters?: ListDiagnosticsFilters, sessionId?: string): Diagnostic[];
 
   /** Parse and type-check an RSLang expression against the current schema context. */
   analyzeExpression(input: AnalyzeExpressionInput, sessionId?: string): AnalysisResult;

package/src/session/persistence.ts

@@ -1,11 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { type DiagnosticRecord, type SessionState } from '../models';
+import { type Diagnostic, type SessionState } from '../models';
 
 export interface PersistedSessionEnvelope {
   state: SessionState;
-  diagnostics: DiagnosticRecord[];
+  diagnostics: Diagnostic[];
 }
 
 const CURRENT_SESSION_FILE = '_current.json';