@rsconcept/rstool 0.1.0

package/src/models/index.ts

@@ -0,0 +1,33 @@
+export { type AnalysisResult, type AnalyzeExpressionInput } from './analysis';
+export {
+  CstType,
+  EvalStatus,
+  RSErrorCode,
+  ValueClass,
+  type BasicBinding,
+  type RSToolErrorDescription,
+  type RSToolValue
+} from './common';
+export {
+  type AddOrUpdateConstituentaInput,
+  type AddOrUpdateConstituentaResult,
+  type ConstituentaDraft,
+  type ConstituentaState
+} from './constituenta';
+export { type DiagnosticRecord, type ListDiagnosticsFilters } from './diagnostic';
+export {
+  type EvaluateConstituentaInput,
+  type EvaluateExpressionInput,
+  type EvaluationResult
+} from './evaluation';
+export {
+  type ClearConstituentaValuesInput,
+  type ModelValueState,
+  type RecalculateModelResult,
+  type SessionModelState,
+  type SetConstituentaValueInput,
+  type SetConstituentaValuesInput
+} from './model-value';
+export { RSToolAgent } from './rstool-agent';
+export { type SessionHandle, type SessionRevision, type SessionState } from './session';
+export { CONTRACT_VERSION, type RSToolAgentContract } from './tool-contract';

package/src/models/model-value.ts

@@ -0,0 +1,31 @@
+import { type BasicBinding, type EvalStatus, type RSToolValue } from './common';
+
+export interface ModelValueState {
+  id: number;
+  /** Frontend type string: `basic` or normalized effective typification. */
+  type: string;
+  value: RSToolValue | BasicBinding;
+}
+
+export interface SessionModelState {
+  items: ModelValueState[];
+}
+
+export interface SetConstituentaValueInput {
+  target: number;
+  /** Optional type override; inferred from schema when omitted. */
+  type?: string;
+  value: RSToolValue | BasicBinding;
+}
+
+export interface SetConstituentaValuesInput {
+  items: SetConstituentaValueInput[];
+}
+
+export interface ClearConstituentaValuesInput {
+  items: number[];
+}
+
+export interface RecalculateModelResult {
+  items: Array<{ id: number; alias: string; value: RSToolValue | null; status: EvalStatus }>;
+}

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

@@ -0,0 +1,300 @@
+import { describe, expect, it } from 'vitest';
+
+import { CstType, EvalStatus, RSErrorCode, RSToolAgent } from './index';
+
+function buildSampleForm(tool: RSToolAgent, sessionId: string) {
+  tool.addOrUpdateConstituenta(sessionId, {
+    draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
+  });
+  tool.addOrUpdateConstituenta(sessionId, {
+    draft: { id: 2, alias: 'D1', cstType: CstType.TERM, definitionFormal: '1+2' }
+  });
+  tool.addOrUpdateConstituenta(sessionId, {
+    draft: { id: 3, alias: 'A1', cstType: CstType.AXIOM, definitionFormal: '1=1' }
+  });
+}
+
+describe('RSToolAgent', () => {
+  it('creates and exports a session', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    const exported = tool.exportSession(session.sessionId);
+    expect(exported).toContain(session.sessionId);
+    expect(exported).toContain('contractVersion');
+  });
+
+  it('analyzes a valid expression', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    const analysis = tool.analyzeExpression(session.sessionId, {
+      expression: '1+2',
+      cstType: CstType.TERM
+    });
+    expect(analysis.success).toBe(true);
+    expect(analysis.diagnostics.length).toBe(0);
+  });
+
+  it('returns syntax diagnostics for invalid expression', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    const analysis = tool.analyzeExpression(session.sessionId, {
+      expression: '(',
+      cstType: CstType.TERM
+    });
+    expect(analysis.success).toBe(false);
+    expect(analysis.diagnostics.length).toBeGreaterThan(0);
+  });
+
+  it('rejects formal definition for constants', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    const result = tool.addOrUpdateConstituenta(session.sessionId, {
+      draft: {
+        id: 11,
+        alias: 'C1',
+        cstType: CstType.CONSTANT,
+        definitionFormal: 'X1'
+      }
+    });
+    expect(result.state.analysis.success).toBe(false);
+    expect(result.diagnostics[0]?.error.code).toBe(RSErrorCode.definitionNotAllowed);
+  });
+
+  it('rejects formal definition for basic sets', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    const result = tool.addOrUpdateConstituenta(session.sessionId, {
+      draft: {
+        id: 12,
+        alias: 'X1',
+        cstType: CstType.BASE,
+        definitionFormal: 'Z'
+      }
+    });
+    expect(result.state.analysis.success).toBe(false);
+    expect(result.diagnostics[0]?.error.code).toBe(RSErrorCode.definitionNotAllowed);
+  });
+
+  it('returns known analysis for empty base definition', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    const result = tool.addOrUpdateConstituenta(session.sessionId, {
+      draft: {
+        id: 13,
+        alias: 'X1',
+        cstType: CstType.BASE,
+        definitionFormal: ''
+      }
+    });
+    expect(result.state.analysis.success).toBe(true);
+    expect(result.state.analysis.type).not.toBeNull();
+    expect(result.state.analysis.valueClass).toBe('value');
+  });
+
+  it('persists term, definitionText, and convention in session state', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    const result = tool.addOrUpdateConstituenta(session.sessionId, {
+      draft: {
+        id: 15,
+        alias: 'D2',
+        cstType: CstType.TERM,
+        definitionFormal: '1',
+        term: 'natural number',
+        definitionText: 'A positive integer',
+        convention: 'Standard arithmetic'
+      }
+    });
+    expect(result.state.term).toBe('natural number');
+    expect(result.state.definitionText).toBe('A positive integer');
+    expect(result.state.convention).toBe('Standard arithmetic');
+
+    const form = tool.getFormState(session.sessionId);
+    expect(form.items[0]).toMatchObject({
+      term: 'natural number',
+      definitionText: 'A positive integer',
+      convention: 'Standard arithmetic'
+    });
+
+    const exported = tool.exportSession(session.sessionId);
+    const imported = tool.importSession(exported);
+    const restored = tool.getFormState(imported.sessionId);
+    expect(restored.items[0]).toMatchObject({
+      term: 'natural number',
+      definitionText: 'A positive integer',
+      convention: 'Standard arithmetic'
+    });
+  });
+
+  it('defaults missing text fields to empty strings', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    const result = tool.addOrUpdateConstituenta(session.sessionId, {
+      draft: {
+        id: 16,
+        alias: 'D3',
+        cstType: CstType.TERM,
+        definitionFormal: '2'
+      }
+    });
+    expect(result.state.term).toBe('');
+    expect(result.state.definitionText).toBe('');
+    expect(result.state.convention).toBe('');
+  });
+
+  it('returns known analysis for empty constant definition', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    const result = tool.addOrUpdateConstituenta(session.sessionId, {
+      draft: {
+        id: 14,
+        alias: 'C1',
+        cstType: CstType.CONSTANT,
+        definitionFormal: ''
+      }
+    });
+    expect(result.state.analysis.success).toBe(true);
+    expect(result.state.analysis.type).not.toBeNull();
+    expect(result.state.analysis.valueClass).toBe('value');
+  });
+});
+
+describe('RSToolAgent modeling and evaluation', () => {
+  it('returns empty model on new session', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    const model = tool.getModelState(session.sessionId);
+    expect(model.items).toEqual([]);
+  });
+
+  it('sets base constituenta binding', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildSampleForm(tool, session.sessionId);
+
+    const model = await tool.setConstituentaValue(session.sessionId, {
+      target: 1,
+      value: { 0: 'zero', 1: 'one' }
+    });
+    expect(model.items).toHaveLength(1);
+    expect(model.items[0]).toMatchObject({
+      id: 1,
+      type: 'basic',
+      value: { 0: 'zero', 1: 'one' }
+    });
+  });
+
+  it('rejects setting inferrable term directly', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildSampleForm(tool, session.sessionId);
+
+    await expect(
+      tool.setConstituentaValue(session.sessionId, {
+        target: 2,
+        value: 3
+      })
+    ).rejects.toThrow(/inferrable/);
+  });
+
+  it('evaluates expression against session context', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildSampleForm(tool, session.sessionId);
+
+    const result = tool.evaluateExpression(session.sessionId, {
+      expression: '1+2',
+      cstType: CstType.TERM
+    });
+    expect(result.success).toBe(true);
+    expect(result.value).toBe(3);
+    expect(result.status).toBe(EvalStatus.HAS_DATA);
+    expect(result.diagnostics).toHaveLength(0);
+  });
+
+  it('evaluates a stored constituenta', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildSampleForm(tool, session.sessionId);
+
+    const result = tool.evaluateConstituenta(session.sessionId, { constituentId: 2 });
+    expect(result.success).toBe(true);
+    expect(result.value).toBe(3);
+    expect(result.status).toBe(EvalStatus.HAS_DATA);
+  });
+
+  it('evaluates axiom constituenta', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildSampleForm(tool, session.sessionId);
+
+    const result = tool.evaluateConstituenta(session.sessionId, { constituentId: 3 });
+    expect(result.success).toBe(true);
+    expect(result.value).toBe(1);
+  });
+
+  it('recalculates inferrable model values', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildSampleForm(tool, session.sessionId);
+
+    const result = tool.recalculateModel(session.sessionId);
+    const d1 = result.items.find(item => item.alias === 'D1');
+    const a1 = result.items.find(item => item.alias === 'A1');
+    expect(d1?.value).toBe(3);
+    expect(d1?.status).toBe(EvalStatus.HAS_DATA);
+    expect(a1?.value).toBe(1);
+    expect(a1?.status).toBe(EvalStatus.HAS_DATA);
+  });
+
+  it('clears model values', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildSampleForm(tool, session.sessionId);
+    await tool.setConstituentaValue(session.sessionId, {
+      target: 1,
+      value: { 0: 'a' }
+    });
+
+    const model = await tool.clearConstituentaValues(session.sessionId, { items: [1] });
+    expect(model.items).toHaveLength(0);
+  });
+
+  it('batch sets model values', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.addOrUpdateConstituenta(session.sessionId, {
+      draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
+    });
+    tool.addOrUpdateConstituenta(session.sessionId, {
+      draft: { id: 2, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' }
+    });
+
+    const model = await tool.setConstituentaValues(session.sessionId, {
+      items: [
+        { target: 1, value: { 0: 'a', 1: 'b' } },
+        { target: 2, value: { 0: 'c' } }
+      ]
+    });
+    expect(model.items).toHaveLength(2);
+  });
+
+  it('exports and imports model state', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildSampleForm(tool, session.sessionId);
+    await tool.setConstituentaValue(session.sessionId, {
+      target: 1,
+      value: { 0: 'zero' }
+    });
+
+    const exported = tool.exportSession(session.sessionId);
+    expect(exported).toContain('"model"');
+
+    const newTool = new RSToolAgent();
+    const imported = newTool.importSession(exported);
+    const model = newTool.getModelState(imported.sessionId);
+    expect(model.items).toHaveLength(1);
+    expect(model.items[0]?.value).toEqual({ 0: 'zero' });
+  });
+});

package/src/models/rstool-agent.ts

@@ -0,0 +1,143 @@
+import { ModelAdapter } from '../mappers/model-adapter';
+import { SchemaAdapter } from '../mappers/schema-adapter';
+import { SessionStore } from '../session/session-store';
+import { type AnalysisResult, type AnalyzeExpressionInput } from './analysis';
+import {
+  type AddOrUpdateConstituentaInput,
+  type AddOrUpdateConstituentaResult
+} from './constituenta';
+import { 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';
+import { CONTRACT_VERSION, type RSToolAgentContract } from './tool-contract';
+
+export class RSToolAgent implements RSToolAgentContract {
+  public readonly contractVersion = CONTRACT_VERSION;
+  private readonly sessions = new SessionStore();
+  private readonly adapter = new SchemaAdapter();
+  private readonly evaluation = new ModelAdapter();
+
+  public createSession(initial?: Partial<SessionState>): SessionHandle {
+    return this.sessions.create(initial, this.contractVersion);
+  }
+
+  public addOrUpdateConstituenta(
+    sessionId: string,
+    input: AddOrUpdateConstituentaInput
+  ): AddOrUpdateConstituentaResult {
+    const envelope = this.sessions.get(sessionId);
+    const { result, diagnostics } = this.adapter.analyzeAgainstSession(envelope.state, input.draft);
+    const state = this.adapter.mergeStateWithDraft(envelope.state, input.draft, result);
+    this.sessions.appendDiagnostics(sessionId, diagnostics);
+    return {
+      state,
+      diagnostics
+    };
+  }
+
+  public analyzeExpression(sessionId: string, input: AnalyzeExpressionInput): AnalysisResult {
+    const envelope = this.sessions.get(sessionId);
+    const { result, diagnostics } = this.adapter.analyzeAgainstSession(envelope.state, {
+      id: -1,
+      alias: '_analysis',
+      cstType: input.cstType,
+      definitionFormal: input.expression
+    });
+    this.sessions.appendDiagnostics(
+      sessionId,
+      diagnostics.map(item => ({ ...item, constituentId: undefined }))
+    );
+    return result;
+  }
+
+  public getFormState(sessionId: string): SessionState {
+    const envelope = this.sessions.get(sessionId);
+    return structuredClone(envelope.state);
+  }
+
+  public listDiagnostics(sessionId: string, filters?: ListDiagnosticsFilters) {
+    return this.sessions.listDiagnostics(sessionId, filters);
+  }
+
+  public commitStep(sessionId: string, message?: string): SessionRevision {
+    return this.sessions.addRevision(sessionId, message);
+  }
+
+  public exportSession(sessionId: string): string {
+    const envelope = this.sessions.get(sessionId);
+    return JSON.stringify(
+      {
+        contractVersion: this.contractVersion,
+        state: envelope.state,
+        diagnostics: envelope.diagnostics
+      },
+      null,
+      2
+    );
+  }
+
+  public importSession(payload: string): SessionHandle {
+    const parsed = JSON.parse(payload) as {
+      state: SessionState;
+    };
+    if (!parsed.state.model) {
+      parsed.state.model = { items: [] };
+    }
+    return this.sessions.create(parsed.state, this.contractVersion);
+  }
+
+  public async setConstituentaValue(
+    sessionId: string,
+    input: SetConstituentaValueInput
+  ): Promise<SessionModelState> {
+    const envelope = this.sessions.get(sessionId);
+    return this.evaluation.setConstituentaValue(envelope.state, input);
+  }
+
+  public async setConstituentaValues(
+    sessionId: string,
+    input: SetConstituentaValuesInput
+  ): Promise<SessionModelState> {
+    const envelope = this.sessions.get(sessionId);
+    return this.evaluation.setConstituentaValues(envelope.state, input);
+  }
+
+  public async clearConstituentaValues(
+    sessionId: string,
+    input: ClearConstituentaValuesInput
+  ): Promise<SessionModelState> {
+    const envelope = this.sessions.get(sessionId);
+    return this.evaluation.clearConstituentaValues(envelope.state, input.items);
+  }
+
+  public getModelState(sessionId: string): SessionModelState {
+    const envelope = this.sessions.get(sessionId);
+    return structuredClone(envelope.state.model);
+  }
+
+  public evaluateExpression(sessionId: string, input: EvaluateExpressionInput): EvaluationResult {
+    const envelope = this.sessions.get(sessionId);
+    return this.evaluation.evaluateExpression(envelope.state, input.expression, input.cstType);
+  }
+
+  public evaluateConstituenta(sessionId: string, input: EvaluateConstituentaInput): EvaluationResult {
+    const envelope = this.sessions.get(sessionId);
+    return this.evaluation.evaluateConstituenta(envelope.state, input.constituentId);
+  }
+
+  public recalculateModel(sessionId: string): RecalculateModelResult {
+    const envelope = this.sessions.get(sessionId);
+    return this.evaluation.recalculateModel(envelope.state);
+  }
+}

package/src/models/session.ts

@@ -0,0 +1,22 @@
+import { type ConstituentaState } from './constituenta';
+import { type SessionModelState } from './model-value';
+
+export interface SessionHandle {
+  sessionId: string;
+  contractVersion: string;
+}
+
+export interface SessionRevision {
+  revisionId: string;
+  at: string;
+  message?: string;
+}
+
+export interface SessionState {
+  sessionId: string;
+  createdAt: string;
+  updatedAt: string;
+  revisions: SessionRevision[];
+  items: ConstituentaState[];
+  model: SessionModelState;
+}

package/src/models/tool-contract.ts

@@ -0,0 +1,47 @@
+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';
+
+export const CONTRACT_VERSION = '1.2.0';
+
+export interface RSToolAgentContract {
+  readonly contractVersion: string;
+  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;
+  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;
+}

package/src/session/session-store.ts

@@ -0,0 +1,81 @@
+import { randomUUID } from 'node:crypto';
+
+import {
+  type DiagnosticRecord,
+  type ListDiagnosticsFilters,
+  type SessionHandle,
+  type SessionRevision,
+  type SessionState
+} from '../models';
+
+interface SessionEnvelope {
+  state: SessionState;
+  diagnostics: DiagnosticRecord[];
+}
+
+export class SessionStore {
+  private sessions = new Map<string, SessionEnvelope>();
+
+  public create(initial?: Partial<SessionState>, contractVersion?: string): SessionHandle {
+    const now = new Date().toISOString();
+    const sessionId = initial?.sessionId ?? randomUUID();
+    const state: SessionState = {
+      sessionId,
+      createdAt: initial?.createdAt ?? now,
+      updatedAt: now,
+      revisions: initial?.revisions ?? [],
+      items: initial?.items ?? [],
+      model: initial?.model ?? { items: [] }
+    };
+    this.sessions.set(sessionId, {
+      state,
+      diagnostics: []
+    });
+    return {
+      sessionId,
+      contractVersion: contractVersion ?? '1.0.0'
+    };
+  }
+
+  public get(sessionId: string): SessionEnvelope {
+    const found = this.sessions.get(sessionId);
+    if (!found) {
+      throw new Error(`Unknown session: ${sessionId}`);
+    }
+    return found;
+  }
+
+  public replaceState(sessionId: string, nextState: SessionState): void {
+    const found = this.get(sessionId);
+    found.state = {
+      ...nextState,
+      updatedAt: new Date().toISOString()
+    };
+  }
+
+  public addRevision(sessionId: string, message?: string): SessionRevision {
+    const found = this.get(sessionId);
+    const revision: SessionRevision = {
+      revisionId: randomUUID(),
+      at: new Date().toISOString(),
+      message
+    };
+    found.state.revisions.push(revision);
+    found.state.updatedAt = revision.at;
+    return revision;
+  }
+
+  public appendDiagnostics(sessionId: string, records: DiagnosticRecord[]): void {
+    const found = this.get(sessionId);
+    found.diagnostics.push(...records);
+    found.state.updatedAt = new Date().toISOString();
+  }
+
+  public listDiagnostics(sessionId: string, filters?: ListDiagnosticsFilters): DiagnosticRecord[] {
+    const found = this.get(sessionId);
+    if (!filters?.constituentId) {
+      return [...found.diagnostics];
+    }
+    return found.diagnostics.filter(record => record.constituentId === filters.constituentId);
+  }
+}