@rsconcept/rstool 0.10.3 → 1.0.0

package/src/models/tool-contract.ts

@@ -1,49 +1,88 @@
-import { type AnalysisResult, type AnalyzeExpressionInput } from './analysis';
-import {
-  type AddOrUpdateConstituentaInput,
-  type AddOrUpdateConstituentaResult
-} from './constituenta';
-import {
-  type DiagnosticRecord,
-  type ListDiagnosticsFilters
-} from './diagnostic';
 import {
-  type EvaluateConstituentaInput,
-  type EvaluateExpressionInput,
-  type EvaluationResult
-} from './evaluation';
-import {
-  type ClearConstituentaValuesInput,
-  type RecalculateModelResult,
-  type SessionModelState,
-  type SetConstituentaValueInput,
-  type SetConstituentaValuesInput
-} from './model-value';
-import {
-  type SessionHandle,
-  type SessionRevision,
-  type SessionState
-} from './session';
+  type ApplySchemaPatchInput,
+  type ApplySchemaPatchResult,
+  type SessionStateDetail,
+  type SessionStateResult
+} from './agent-workflow';
+import { type AnalysisResult, type AnalyzeExpressionInput } from './analysis';
+import { type DiagnosticRecord, 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';
 
-export const CONTRACT_VERSION = '1.4.0';
+/** Agent-visible contract version; bump on breaking API changes. */
+export const CONTRACT_VERSION = '2.0.0';
 
+/** Options for constructing an {@link RSToolAgent}. */
+export interface RSToolAgentOptions {
+  /** When set, sessions are persisted to this directory and survive process restarts. */
+  persistenceDir?: string;
+}
+
+/**
+ * Public method surface of {@link RSToolAgent}.
+ *
+ * Each method accepts an optional `sessionId`; when omitted, the current session is used
+ * (or a new one is created where noted).
+ */
 export interface RSToolAgentContract {
+  /** Current contract version string (same as {@link CONTRACT_VERSION}). */
   readonly contractVersion: string;
+
+  /** Return the current session, or create one with optional `initial` metadata. */
+  ensureSession(initial?: Partial<SessionState>): SessionHandle;
+
+  /** Create a new session and make it current. */
   createSession(initial?: Partial<SessionState>): SessionHandle;
-  addOrUpdateConstituenta(sessionId: string, input: AddOrUpdateConstituentaInput): AddOrUpdateConstituentaResult;
-  analyzeExpression(sessionId: string, input: AnalyzeExpressionInput): AnalysisResult;
-  getFormState(sessionId: string): SessionState;
-  listDiagnostics(sessionId: string, filters?: ListDiagnosticsFilters): DiagnosticRecord[];
-  commitStep(sessionId: string, message?: string): SessionRevision;
-  exportSession(sessionId: string): string;
-  exportPortalSchema(sessionId: string): string;
-  exportPortalModel(sessionId: string): string;
-  importSession(payload: string): SessionHandle;
-  setConstituentaValue(sessionId: string, input: SetConstituentaValueInput): Promise<SessionModelState>;
-  setConstituentaValues(sessionId: string, input: SetConstituentaValuesInput): Promise<SessionModelState>;
-  clearConstituentaValues(sessionId: string, input: ClearConstituentaValuesInput): Promise<SessionModelState>;
-  getModelState(sessionId: string): SessionModelState;
-  evaluateExpression(sessionId: string, input: EvaluateExpressionInput): EvaluationResult;
-  evaluateConstituenta(sessionId: string, input: EvaluateConstituentaInput): EvaluationResult;
-  recalculateModel(sessionId: string): RecalculateModelResult;
+
+  /** Return the current session handle, or `null` when none is active. */
+  getCurrentSession(): SessionHandle | null;
+
+  /** Switch the active session; throws when `sessionId` is unknown. */
+  setCurrentSession(sessionId: string): SessionHandle;
+
+  /** Apply constituent patches to the schema (analyze, merge, optionally commit). */
+  applySchemaPatch(input: ApplySchemaPatchInput, sessionId?: string): ApplySchemaPatchResult;
+
+  /** 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[];
+
+  /** Parse and type-check an RSLang expression against the current schema context. */
+  analyzeExpression(input: AnalyzeExpressionInput, sessionId?: string): AnalysisResult;
+
+  /** Record a revision checkpoint with an optional message. */
+  commitStep(message?: string, sessionId?: string): SessionRevision;
+
+  /** Export the session as a JSON string (state + diagnostics). */
+  exportSession(sessionId?: string): string;
+
+  /** Export schema or model payload in Portal JSON format. */
+  exportPortal(input: ExportPortalInput, sessionId?: string): ExportPortalResult;
+
+  /**
+   * Import a session export or Portal JSON payload and make the new session current.
+   *
+   * When `kind` is `'auto'`, the payload shape is detected automatically.
+   */
+  importData(payload: string | object, kind?: ImportDataKind): SessionHandle;
+
+  /** Set or clear model values for constituents; returns the updated model state. */
+  setModelValues(input: SetModelValuesInput, sessionId?: string): Promise<SessionModelState>;
+
+  /** Return a deep clone of the session model state. */
+  getModelState(sessionId?: string): SessionModelState;
+
+  /**
+   * Evaluate a stored constituent or a scratch expression.
+   *
+   * Provide `constituentId`, or both `expression` and `cstType`.
+   */
+  evaluate(input: EvaluateInput, sessionId?: string): EvaluationResult;
+
+  /** Recompute derived model values for all constituents. */
+  recalculateModel(sessionId?: string): RecalculateModelResult;
 }

package/src/session/batch-apply.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+
+import { CstType } from '../models';
+import { orderDrafts } from './batch-apply';
+
+describe('orderDrafts', () => {
+  it('orders dependents after suppliers', () => {
+    const ordered = orderDrafts(
+      [
+        {
+          id: 1,
+          alias: 'X1',
+          cstType: CstType.BASE,
+          definitionFormal: '',
+          term: '',
+          definitionText: '',
+          convention: '',
+          analysis: { success: true, type: null, valueClass: 'value', diagnostics: [] }
+        }
+      ],
+      [
+        { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' },
+        { id: 2, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' }
+      ]
+    );
+    expect(ordered.map(draft => draft.alias)).toEqual(['S1', 'D1']);
+  });
+});

package/src/session/batch-apply.ts

@@ -0,0 +1,47 @@
+import { Graph } from '@rsconcept/domain/graph/graph';
+import { extractGlobals } from '@rsconcept/domain/rslang/api';
+
+import { type ConstituentaDraft, type ConstituentaState } from '../models';
+
+/** Order drafts so suppliers are applied before dependents. */
+export function orderDrafts(sessionItems: ConstituentaState[], drafts: ConstituentaDraft[]): ConstituentaDraft[] {
+  const merged = new Map<number, ConstituentaDraft>();
+  for (const item of sessionItems) {
+    merged.set(item.id, {
+      id: item.id,
+      alias: item.alias,
+      cstType: item.cstType,
+      definitionFormal: item.definitionFormal
+    });
+  }
+  for (const draft of drafts) {
+    merged.set(draft.id, draft);
+  }
+
+  const graph = new Graph<number>();
+  const aliasToId = new Map<string, number>();
+  for (const [id, draft] of merged) {
+    graph.addNode(id);
+    aliasToId.set(draft.alias, id);
+  }
+
+  for (const [id, draft] of merged) {
+    if (!draft.definitionFormal) {
+      continue;
+    }
+    for (const alias of extractGlobals(draft.definitionFormal)) {
+      const depId = aliasToId.get(alias);
+      if (depId !== undefined && depId !== id) {
+        graph.addEdge(depId, id);
+      }
+    }
+  }
+
+  const draftIds = new Set(drafts.map(draft => draft.id));
+  const topoIds = graph.topologicalOrder().filter(id => draftIds.has(id));
+  const seen = new Set(topoIds);
+  const missing = drafts.filter(draft => !seen.has(draft.id)).map(draft => draft.id);
+
+  const orderedIds = [...topoIds, ...missing];
+  return orderedIds.map(id => drafts.find(draft => draft.id === id)!).filter(Boolean);
+}

package/src/session/persistence.ts

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { type DiagnosticRecord, type SessionState } from '../models';
+
+export interface PersistedSessionEnvelope {
+  state: SessionState;
+  diagnostics: DiagnosticRecord[];
+}
+
+const CURRENT_SESSION_FILE = '_current.json';
+
+export class SessionPersistence {
+  private readonly dir: string;
+
+  public constructor(dir: string) {
+    this.dir = dir;
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  public save(sessionId: string, envelope: PersistedSessionEnvelope): void {
+    fs.writeFileSync(this.filePath(sessionId), JSON.stringify(envelope, null, 2), 'utf-8');
+  }
+
+  public load(sessionId: string): PersistedSessionEnvelope | null {
+    const file = this.filePath(sessionId);
+    if (!fs.existsSync(file)) {
+      return null;
+    }
+    return JSON.parse(fs.readFileSync(file, 'utf-8')) as PersistedSessionEnvelope;
+  }
+
+  public delete(sessionId: string): void {
+    const file = this.filePath(sessionId);
+    if (fs.existsSync(file)) {
+      fs.unlinkSync(file);
+    }
+  }
+
+  public saveCurrentSessionId(sessionId: string | null): void {
+    fs.writeFileSync(path.join(this.dir, CURRENT_SESSION_FILE), JSON.stringify({ sessionId }, null, 2), 'utf-8');
+  }
+
+  public loadCurrentSessionId(): string | null {
+    const file = path.join(this.dir, CURRENT_SESSION_FILE);
+    if (!fs.existsSync(file)) {
+      return null;
+    }
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8')) as { sessionId?: string | null };
+    return parsed.sessionId ?? null;
+  }
+
+  private filePath(sessionId: string): string {
+    return path.join(this.dir, `${sessionId}.json`);
+  }
+}

package/src/session/session-store.ts

@@ -7,6 +7,11 @@ import {
   type SessionRevision,
   type SessionState
 } from '../models';
+import { SessionPersistence, type PersistedSessionEnvelope } from './persistence';
+
+export interface SessionStoreOptions {
+  persistenceDir?: string;
+}
 
 interface SessionEnvelope {
   state: SessionState;
@@ -15,6 +20,11 @@ interface SessionEnvelope {
 
 export class SessionStore {
   private sessions = new Map<string, SessionEnvelope>();
+  private readonly persistence: SessionPersistence | null;
+
+  public constructor(options: SessionStoreOptions = {}) {
+    this.persistence = options.persistenceDir ? new SessionPersistence(options.persistenceDir) : null;
+  }
 
   public create(initial?: Partial<SessionState>, contractVersion?: string): SessionHandle {
     const now = new Date().toISOString();
@@ -30,10 +40,12 @@ export class SessionStore {
       items: initial?.items ?? [],
       model: initial?.model ?? { items: [] }
     };
-    this.sessions.set(sessionId, {
+    const envelope: SessionEnvelope = {
       state,
       diagnostics: []
-    });
+    };
+    this.sessions.set(sessionId, envelope);
+    this.persist(sessionId, envelope);
     return {
       sessionId,
       contractVersion: contractVersion ?? '1.0.0'
@@ -41,19 +53,24 @@ export class SessionStore {
   }
 
   public get(sessionId: string): SessionEnvelope {
-    const found = this.sessions.get(sessionId);
+    const found = this.sessions.get(sessionId) ?? this.loadFromDisk(sessionId);
     if (!found) {
       throw new Error(`Unknown session: ${sessionId}`);
     }
     return found;
   }
 
+  public has(sessionId: string): boolean {
+    return this.sessions.has(sessionId) || this.persistence?.load(sessionId) !== null;
+  }
+
   public replaceState(sessionId: string, nextState: SessionState): void {
     const found = this.get(sessionId);
     found.state = {
       ...nextState,
       updatedAt: new Date().toISOString()
     };
+    this.persist(sessionId, found);
   }
 
   public addRevision(sessionId: string, message?: string): SessionRevision {
@@ -65,13 +82,28 @@ export class SessionStore {
     };
     found.state.revisions.push(revision);
     found.state.updatedAt = revision.at;
+    this.persist(sessionId, found);
     return revision;
   }
 
-  public appendDiagnostics(sessionId: string, records: DiagnosticRecord[]): void {
+  /** Replace active diagnostics for one constituent (or scratch when constituentId is undefined). */
+  public replaceDiagnosticsForConstituent(
+    sessionId: string,
+    constituentId: number | undefined,
+    records: DiagnosticRecord[]
+  ): void {
     const found = this.get(sessionId);
+    found.diagnostics = found.diagnostics.filter(record => record.constituentId !== constituentId);
     found.diagnostics.push(...records);
     found.state.updatedAt = new Date().toISOString();
+    this.persist(sessionId, found);
+  }
+
+  public setDiagnostics(sessionId: string, records: DiagnosticRecord[]): void {
+    const found = this.get(sessionId);
+    found.diagnostics = [...records];
+    found.state.updatedAt = new Date().toISOString();
+    this.persist(sessionId, found);
   }
 
   public listDiagnostics(sessionId: string, filters?: ListDiagnosticsFilters): DiagnosticRecord[] {
@@ -81,4 +113,35 @@ export class SessionStore {
     }
     return found.diagnostics.filter(record => record.constituentId === filters.constituentId);
   }
+
+  public snapshot(sessionId: string): SessionEnvelope {
+    const found = this.get(sessionId);
+    return structuredClone(found);
+  }
+
+  public restore(sessionId: string, snapshot: SessionEnvelope): void {
+    this.sessions.set(sessionId, structuredClone(snapshot));
+    this.persist(sessionId, this.sessions.get(sessionId)!);
+  }
+
+  public saveCurrentSessionId(sessionId: string | null): void {
+    this.persistence?.saveCurrentSessionId(sessionId);
+  }
+
+  public loadCurrentSessionId(): string | null {
+    return this.persistence?.loadCurrentSessionId() ?? null;
+  }
+
+  private loadFromDisk(sessionId: string): SessionEnvelope | null {
+    const loaded = this.persistence?.load(sessionId);
+    if (!loaded) {
+      return null;
+    }
+    this.sessions.set(sessionId, loaded);
+    return loaded;
+  }
+
+  private persist(sessionId: string, envelope: SessionEnvelope): void {
+    this.persistence?.save(sessionId, envelope as PersistedSessionEnvelope);
+  }
 }

package/src/wrapper/client.ts

@@ -2,6 +2,7 @@ import { spawn, type ChildProcessByStdio } from 'node:child_process';
 import readline from 'node:readline';
 import { type Readable, type Writable } from 'node:stream';
 
+/** One JSON line emitted by the stdio wrapper (request response or ready event). */
 export interface WrapperResponse<T = unknown> {
   id: string | number | null;
   ok: boolean;
@@ -13,19 +14,32 @@ export interface WrapperResponse<T = unknown> {
   };
 }
 
+/** Options for spawning the `rstool-wrapper` child process. */
 export interface RSToolWrapperClientOptions {
+  /** Executable to spawn. Default: `npm`. */
   command?: string;
+  /** Arguments passed to `command`. Default: `['run', 'wrapper']`. */
   args?: string[];
+  /** Working directory for the child process. Default: `process.cwd()`. */
   cwd?: string;
+  /** Whether to run the command in a shell. Default: `true`. */
   shell?: boolean;
 }
 
+/**
+ * JSON-RPC client for the `rstool-wrapper` stdio process.
+ *
+ * Sends one JSON request per line on stdin and reads one JSON response per line from stdout.
+ */
 export class RSToolWrapperClient {
   private process: ChildProcessByStdio<Writable, Readable, null>;
   private input: readline.Interface;
   private pending = new Map<string, (value: WrapperResponse) => void>();
   private requestCounter = 1;
 
+  /**
+   * @param options - Spawn configuration; defaults run `npm run wrapper` in the current directory.
+   */
   public constructor(options: RSToolWrapperClientOptions = {}) {
     this.process = spawn(options.command ?? 'npm', options.args ?? ['run', 'wrapper'], {
       cwd: options.cwd ?? process.cwd(),
@@ -39,6 +53,7 @@ export class RSToolWrapperClient {
     this.input.on('line', line => this.handleLine(line));
   }
 
+  /** Block until the wrapper emits its initial `{ ready: true }` event. */
   public async waitUntilReady(): Promise<void> {
     for (;;) {
       const line = await this.readOneEvent();
@@ -54,6 +69,13 @@ export class RSToolWrapperClient {
     }
   }
 
+  /**
+   * Invoke a wrapper method and return its `result` field.
+   *
+   * @param method - Stdio method name (matches {@link RSToolAgentContract} operations).
+   * @param params - Method parameters object.
+   * @throws When the wrapper responds with `ok: false`.
+   */
   public async call<T>(method: string, params: unknown = {}): Promise<T> {
     const id = String(this.requestCounter++);
     const payload = JSON.stringify({ id, method, params });
@@ -68,6 +90,7 @@ export class RSToolWrapperClient {
     return response.result as T;
   }
 
+  /** Close stdin and terminate the wrapper process. */
   public async close(): Promise<void> {
     this.input.close();
     this.process.stdin.end();

package/src/wrapper/stdio-wrapper.ts

@@ -20,25 +20,25 @@ interface StdioResponse {
   };
 }
 
-const tool = new RSToolAgent();
+const persistenceDir = process.env.RSTOOL_PERSISTENCE_DIR;
+const tool = new RSToolAgent(persistenceDir ? { persistenceDir } : {});
 
 const METHODS = [
+  'ensureSession',
   'createSession',
-  'addOrUpdateConstituenta',
-  'analyzeExpression',
-  'getFormState',
+  'getCurrentSession',
+  'setCurrentSession',
+  'applySchemaPatch',
+  'getSessionState',
   'listDiagnostics',
+  'analyzeExpression',
   'commitStep',
   'exportSession',
-  'exportPortalSchema',
-  'exportPortalModel',
-  'importSession',
-  'setConstituentaValue',
-  'setConstituentaValues',
-  'clearConstituentaValues',
+  'exportPortal',
+  'importData',
+  'setModelValues',
   'getModelState',
-  'evaluateExpression',
-  'evaluateConstituenta',
+  'evaluate',
   'recalculateModel'
 ] as const;
 
@@ -68,115 +68,125 @@ function requiredString(input: Record<string, unknown>, key: string): string {
   return value;
 }
 
+function optionalSessionId(input: Record<string, unknown>): string | undefined {
+  const value = input.sessionId;
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function omitSessionId(input: Record<string, unknown>): Record<string, unknown> {
+  const { sessionId: _sessionId, ...rest } = input;
+  return rest;
+}
+
 async function handleRequest(request: StdioRequest): Promise<StdioResponse> {
   try {
     const params = asObject(request.params);
     switch (request.method) {
       case 'ping':
-        return { id: request.id, ok: true, result: { pong: true } };
+        return { id: request.id, ok: true, result: { pong: true, contractVersion: tool.contractVersion } };
       case 'methods':
         return { id: request.id, ok: true, result: METHODS };
-      case 'createSession':
+      case 'ensureSession':
         return {
           id: request.id,
           ok: true,
-          result: tool.createSession(params.initial as never)
+          result: tool.ensureSession(params.initial as never)
         };
-      case 'addOrUpdateConstituenta':
+      case 'createSession':
         return {
           id: request.id,
           ok: true,
-          result: tool.addOrUpdateConstituenta(requiredString(params, 'sessionId'), params.input as never)
+          result: tool.createSession(params.initial as never)
         };
-      case 'analyzeExpression':
+      case 'getCurrentSession':
         return {
           id: request.id,
           ok: true,
-          result: tool.analyzeExpression(requiredString(params, 'sessionId'), params.input as never)
+          result: tool.getCurrentSession()
         };
-      case 'getFormState':
+      case 'setCurrentSession':
         return {
           id: request.id,
           ok: true,
-          result: tool.getFormState(requiredString(params, 'sessionId'))
+          result: tool.setCurrentSession(requiredString(params, 'sessionId'))
         };
-      case 'listDiagnostics':
+      case 'applySchemaPatch':
         return {
           id: request.id,
           ok: true,
-          result: tool.listDiagnostics(requiredString(params, 'sessionId'), params.filters as never)
+          result: tool.applySchemaPatch(omitSessionId(params) as never, optionalSessionId(params))
         };
-      case 'commitStep':
+      case 'getSessionState':
         return {
           id: request.id,
           ok: true,
-          result: tool.commitStep(requiredString(params, 'sessionId'), params.message as string | undefined)
+          result: tool.getSessionState(
+            (params.detail as 'summary' | 'full' | undefined) ?? 'summary',
+            optionalSessionId(params)
+          )
         };
-      case 'exportSession':
+      case 'listDiagnostics': {
+        const constituentId = params.constituentId;
+        const filters = typeof constituentId === 'number' ? { constituentId } : (params.filters as never);
         return {
           id: request.id,
           ok: true,
-          result: tool.exportSession(requiredString(params, 'sessionId'))
+          result: tool.listDiagnostics(filters, optionalSessionId(params))
         };
-      case 'exportPortalSchema':
+      }
+      case 'analyzeExpression':
         return {
           id: request.id,
           ok: true,
-          result: tool.exportPortalSchema(requiredString(params, 'sessionId'))
+          result: tool.analyzeExpression(omitSessionId(params) as never, optionalSessionId(params))
         };
-      case 'exportPortalModel':
+      case 'commitStep':
         return {
           id: request.id,
           ok: true,
-          result: tool.exportPortalModel(requiredString(params, 'sessionId'))
+          result: tool.commitStep(params.message as string | undefined, optionalSessionId(params))
         };
-      case 'importSession':
+      case 'exportSession':
         return {
           id: request.id,
           ok: true,
-          result: tool.importSession(requiredString(params, 'payload'))
+          result: tool.exportSession(optionalSessionId(params))
         };
-      case 'setConstituentaValue':
+      case 'exportPortal':
         return {
           id: request.id,
           ok: true,
-          result: await tool.setConstituentaValue(requiredString(params, 'sessionId'), params.input as never)
+          result: tool.exportPortal(omitSessionId(params) as never, optionalSessionId(params))
         };
-      case 'setConstituentaValues':
+      case 'importData':
         return {
           id: request.id,
           ok: true,
-          result: await tool.setConstituentaValues(requiredString(params, 'sessionId'), params.input as never)
+          result: tool.importData(params.payload as string | object, params.kind as never)
         };
-      case 'clearConstituentaValues':
+      case 'setModelValues':
         return {
           id: request.id,
           ok: true,
-          result: await tool.clearConstituentaValues(requiredString(params, 'sessionId'), params.input as never)
+          result: await tool.setModelValues(omitSessionId(params) as never, optionalSessionId(params))
         };
       case 'getModelState':
         return {
           id: request.id,
           ok: true,
-          result: tool.getModelState(requiredString(params, 'sessionId'))
-        };
-      case 'evaluateExpression':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.evaluateExpression(requiredString(params, 'sessionId'), params.input as never)
+          result: tool.getModelState(optionalSessionId(params))
         };
-      case 'evaluateConstituenta':
+      case 'evaluate':
         return {
           id: request.id,
           ok: true,
-          result: tool.evaluateConstituenta(requiredString(params, 'sessionId'), params.input as never)
+          result: tool.evaluate(omitSessionId(params) as never, optionalSessionId(params))
         };
       case 'recalculateModel':
         return {
           id: request.id,
           ok: true,
-          result: tool.recalculateModel(requiredString(params, 'sessionId'))
+          result: tool.recalculateModel(optionalSessionId(params))
         };
       default:
         return {