@rsconcept/rstool 0.10.3 → 1.0.0

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

@@ -1,17 +1,21 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 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' }
-  });
+  tool.applySchemaPatch(
+    {
+      items: [{ alias: 'X1' }, { alias: 'D1', definitionFormal: '1+2' }, { alias: 'A1', definitionFormal: '1=1' }]
+    },
+    sessionId
+  );
+}
+
+function fullState(tool: RSToolAgent, sessionId?: string) {
+  return tool.getSessionState('full', sessionId) as import('./session').SessionState;
 }
 
 describe('RSToolAgent', () => {
@@ -26,10 +30,7 @@ describe('RSToolAgent', () => {
   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
-    });
+    const analysis = tool.analyzeExpression({ expression: '1+2', cstType: CstType.TERM }, session.sessionId);
     expect(analysis.success).toBe(true);
     expect(analysis.diagnostics.length).toBe(0);
   });
@@ -37,10 +38,7 @@ describe('RSToolAgent', () => {
   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
-    });
+    const analysis = tool.analyzeExpression({ expression: '(', cstType: CstType.TERM }, session.sessionId);
     expect(analysis.success).toBe(false);
     expect(analysis.diagnostics.length).toBeGreaterThan(0);
   });
@@ -48,68 +46,64 @@ describe('RSToolAgent', () => {
   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);
+    const result = tool.applySchemaPatch(
+      {
+        items: [{ alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: 'X1' }]
+      },
+      session.sessionId
+    );
+    expect(result.success).toBe(false);
+    expect(result.failed[0]?.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);
+    const result = tool.applySchemaPatch(
+      {
+        items: [{ alias: 'X1', cstType: CstType.BASE, definitionFormal: 'Z' }]
+      },
+      session.sessionId
+    );
+    expect(result.success).toBe(false);
+    expect(result.failed[0]?.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');
+    const result = tool.applySchemaPatch(
+      {
+        items: [{ alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }]
+      },
+      session.sessionId
+    );
+    expect(result.success).toBe(true);
+    const state = fullState(tool, session.sessionId);
+    expect(state.items[0]?.analysis.type).not.toBeNull();
+    expect(state.items[0]?.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);
+    tool.applySchemaPatch(
+      {
+        items: [
+          {
+            alias: 'D2',
+            cstType: CstType.TERM,
+            definitionFormal: '1',
+            term: 'natural number',
+            definitionText: 'A positive integer',
+            convention: 'Standard arithmetic'
+          }
+        ]
+      },
+      session.sessionId
+    );
+
+    const form = fullState(tool, session.sessionId);
     expect(form.items[0]).toMatchObject({
       term: 'natural number',
       definitionText: 'A positive integer',
@@ -117,8 +111,8 @@ describe('RSToolAgent', () => {
     });
 
     const exported = tool.exportSession(session.sessionId);
-    const imported = tool.importSession(exported);
-    const restored = tool.getFormState(imported.sessionId);
+    const imported = tool.importData(exported, 'session');
+    const restored = fullState(tool, imported.sessionId);
     expect(restored.items[0]).toMatchObject({
       term: 'natural number',
       definitionText: 'A positive integer',
@@ -134,13 +128,13 @@ describe('RSToolAgent', () => {
       comment: 'Example schema'
     });
 
-    expect(tool.getFormState(session.sessionId)).toMatchObject({
+    expect(fullState(tool, session.sessionId)).toMatchObject({
       alias: 'KIN',
       title: 'Kinship',
       comment: 'Example schema'
     });
 
-    const exported = JSON.parse(tool.exportPortalSchema(session.sessionId)) as {
+    const exported = JSON.parse(tool.exportPortal({ kind: 'schema' }, session.sessionId) as string) as {
       title: string;
       alias: string;
       description: string;
@@ -155,19 +149,23 @@ describe('RSToolAgent', () => {
   it('exports schema data for Portal JSON import', () => {
     const tool = new RSToolAgent();
     const session = tool.createSession();
-    tool.addOrUpdateConstituenta(session.sessionId, {
-      draft: {
-        id: 15,
-        alias: 'D2',
-        cstType: CstType.TERM,
-        definitionFormal: '1',
-        term: 'natural number',
-        definitionText: 'A positive integer',
-        convention: 'Standard arithmetic'
-      }
-    });
-
-    const exported = JSON.parse(tool.exportPortalSchema(session.sessionId)) as {
+    tool.applySchemaPatch(
+      {
+        items: [
+          {
+            alias: 'D2',
+            cstType: CstType.TERM,
+            definitionFormal: '1',
+            term: 'natural number',
+            definitionText: 'A positive integer',
+            convention: 'Standard arithmetic'
+          }
+        ]
+      },
+      session.sessionId
+    );
+
+    const exported = JSON.parse(tool.exportPortal({ kind: 'schema' }, session.sessionId) as string) as {
       contract_version: string;
       title: string;
       alias: string;
@@ -182,7 +180,6 @@ describe('RSToolAgent', () => {
     expect(exported.description).toBe('');
 
     expect(exported.items[0]).toMatchObject({
-      id: 15,
       alias: 'D2',
       cst_type: CstType.TERM,
       definition_formal: '1',
@@ -198,12 +195,9 @@ describe('RSToolAgent', () => {
     const tool = new RSToolAgent();
     const session = tool.createSession();
     buildSampleForm(tool, session.sessionId);
-    await tool.setConstituentaValue(session.sessionId, {
-      target: 1,
-      value: { 1: 'Alice' }
-    });
+    await tool.setModelValues({ set: [{ target: 1, value: { 1: 'Alice' } }] }, session.sessionId);
 
-    const exported = JSON.parse(tool.exportPortalModel(session.sessionId)) as {
+    const exported = JSON.parse(tool.exportPortal({ kind: 'model' }, session.sessionId) as string) as {
       contract_version: string;
       title: string;
       alias: string;
@@ -227,33 +221,31 @@ describe('RSToolAgent', () => {
   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('');
+    tool.applySchemaPatch(
+      {
+        items: [{ alias: 'D3', cstType: CstType.TERM, definitionFormal: '2' }]
+      },
+      session.sessionId
+    );
+    const state = fullState(tool, session.sessionId);
+    expect(state.items[0]?.term).toBe('');
+    expect(state.items[0]?.definitionText).toBe('');
+    expect(state.items[0]?.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');
+    const result = tool.applySchemaPatch(
+      {
+        items: [{ alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' }]
+      },
+      session.sessionId
+    );
+    expect(result.success).toBe(true);
+    const state = fullState(tool, session.sessionId);
+    expect(state.items[0]?.analysis.type).not.toBeNull();
+    expect(state.items[0]?.analysis.valueClass).toBe('value');
   });
 });
 
@@ -270,10 +262,10 @@ describe('RSToolAgent modeling and evaluation', () => {
     const session = tool.createSession();
     buildSampleForm(tool, session.sessionId);
 
-    const model = await tool.setConstituentaValue(session.sessionId, {
-      target: 1,
-      value: { 0: 'zero', 1: 'one' }
-    });
+    const model = await tool.setModelValues(
+      { set: [{ target: 1, value: { 0: 'zero', 1: 'one' } }] },
+      session.sessionId
+    );
     expect(model.items).toHaveLength(1);
     expect(model.items[0]).toMatchObject({
       id: 1,
@@ -287,12 +279,9 @@ describe('RSToolAgent modeling and evaluation', () => {
     const session = tool.createSession();
     buildSampleForm(tool, session.sessionId);
 
-    await expect(
-      tool.setConstituentaValue(session.sessionId, {
-        target: 2,
-        value: 3
-      })
-    ).rejects.toThrow(/inferrable/);
+    await expect(tool.setModelValues({ set: [{ target: 2, value: 3 }] }, session.sessionId)).rejects.toThrow(
+      /inferrable/
+    );
   });
 
   it('evaluates expression against session context', () => {
@@ -300,10 +289,7 @@ describe('RSToolAgent modeling and evaluation', () => {
     const session = tool.createSession();
     buildSampleForm(tool, session.sessionId);
 
-    const result = tool.evaluateExpression(session.sessionId, {
-      expression: '1+2',
-      cstType: CstType.TERM
-    });
+    const result = tool.evaluate({ expression: '1+2', cstType: CstType.TERM }, session.sessionId);
     expect(result.success).toBe(true);
     expect(result.value).toBe(3);
     expect(result.status).toBe(EvalStatus.HAS_DATA);
@@ -315,7 +301,7 @@ describe('RSToolAgent modeling and evaluation', () => {
     const session = tool.createSession();
     buildSampleForm(tool, session.sessionId);
 
-    const result = tool.evaluateConstituenta(session.sessionId, { constituentId: 2 });
+    const result = tool.evaluate({ constituentId: 2 }, session.sessionId);
     expect(result.success).toBe(true);
     expect(result.value).toBe(3);
     expect(result.status).toBe(EvalStatus.HAS_DATA);
@@ -326,7 +312,7 @@ describe('RSToolAgent modeling and evaluation', () => {
     const session = tool.createSession();
     buildSampleForm(tool, session.sessionId);
 
-    const result = tool.evaluateConstituenta(session.sessionId, { constituentId: 3 });
+    const result = tool.evaluate({ constituentId: 3 }, session.sessionId);
     expect(result.success).toBe(true);
     expect(result.value).toBe(1);
   });
@@ -349,31 +335,31 @@ describe('RSToolAgent modeling and evaluation', () => {
     const tool = new RSToolAgent();
     const session = tool.createSession();
     buildSampleForm(tool, session.sessionId);
-    await tool.setConstituentaValue(session.sessionId, {
-      target: 1,
-      value: { 0: 'a' }
-    });
+    await tool.setModelValues({ set: [{ target: 1, value: { 0: 'a' } }] }, session.sessionId);
 
-    const model = await tool.clearConstituentaValues(session.sessionId, { items: [1] });
+    const model = await tool.setModelValues({ clear: [1] }, session.sessionId);
     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: '' }
-    });
+    tool.applySchemaPatch(
+      {
+        items: [{ alias: 'X1' }, { alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' }]
+      },
+      session.sessionId
+    );
 
-    const model = await tool.setConstituentaValues(session.sessionId, {
-      items: [
-        { target: 1, value: { 0: 'a', 1: 'b' } },
-        { target: 2, value: { 0: 'c' } }
-      ]
-    });
+    const model = await tool.setModelValues(
+      {
+        set: [
+          { target: 1, value: { 0: 'a', 1: 'b' } },
+          { target: 2, value: { 0: 'c' } }
+        ]
+      },
+      session.sessionId
+    );
     expect(model.items).toHaveLength(2);
   });
 
@@ -381,18 +367,185 @@ describe('RSToolAgent modeling and evaluation', () => {
     const tool = new RSToolAgent();
     const session = tool.createSession();
     buildSampleForm(tool, session.sessionId);
-    await tool.setConstituentaValue(session.sessionId, {
-      target: 1,
-      value: { 0: 'zero' }
-    });
+    await tool.setModelValues({ set: [{ target: 1, value: { 0: 'zero' } }] }, session.sessionId);
 
     const exported = tool.exportSession(session.sessionId);
     expect(exported).toContain('"model"');
 
     const newTool = new RSToolAgent();
-    const imported = newTool.importSession(exported);
+    const imported = newTool.importData(exported, 'session');
     const model = newTool.getModelState(imported.sessionId);
     expect(model.items).toHaveLength(1);
     expect(model.items[0]?.value).toEqual({ 0: 'zero' });
   });
 });
+
+describe('RSToolAgent agent ergonomics', () => {
+  it('tracks current session and allows omitting sessionId', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession({ title: 'Active' });
+    expect(tool.getCurrentSession()?.sessionId).toBe(session.sessionId);
+    expect(fullState(tool).title).toBe('Active');
+  });
+
+  it('auto-creates a session when sessionId is omitted', () => {
+    const tool = new RSToolAgent();
+    const result = tool.applySchemaPatch({
+      items: [{ alias: 'X1' }]
+    });
+
+    expect(result.success).toBe(true);
+    expect(tool.getCurrentSession()).not.toBeNull();
+    expect(fullState(tool).items).toHaveLength(1);
+  });
+
+  it('applies agent schema patches with inferred ids and cstType', () => {
+    const tool = new RSToolAgent();
+
+    const result = tool.applySchemaPatch({
+      initial: { title: 'Agent patch' },
+      commitMessage: 'initial schema',
+      items: [
+        { alias: 'D1', definitionFormal: 'Pr1(S1)' },
+        { alias: 'X1' },
+        { alias: 'S1', definitionFormal: 'ℬ(X1×X1)' }
+      ]
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.summary.title).toBe('Agent patch');
+    expect(result.summary.itemCount).toBe(3);
+    expect(result.revision?.message).toBe('initial schema');
+    expect(fullState(tool).items.map(item => item.alias)).toEqual(['X1', 'S1', 'D1']);
+    expect(fullState(tool).items.map(item => item.cstType)).toEqual([CstType.BASE, CstType.STRUCTURED, CstType.TERM]);
+  });
+
+  it('exports Portal payloads as structured objects', () => {
+    const tool = new RSToolAgent();
+    tool.applySchemaPatch({
+      items: [{ alias: 'D1', definitionFormal: '1+2' }]
+    });
+
+    const schema = tool.exportPortal({ kind: 'schema', format: 'object' });
+    expect(schema).toMatchObject({ items: [{ alias: 'D1', cst_type: CstType.TERM }] });
+    expect(JSON.parse(tool.exportPortal({ kind: 'schema' }) as string).items[0]).toMatchObject(
+      (schema as { items: unknown[] }).items[0] as object
+    );
+  });
+
+  it('replaces active diagnostics per constituent on upsert', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch(
+      { mode: 'best_effort', items: [{ alias: 'X1', cstType: CstType.BASE, definitionFormal: 'Z' }] },
+      session.sessionId
+    );
+    expect(tool.listDiagnostics(undefined, session.sessionId)).toHaveLength(1);
+
+    tool.applySchemaPatch({ items: [{ alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }] }, session.sessionId);
+    expect(tool.listDiagnostics(undefined, session.sessionId)).toHaveLength(0);
+  });
+
+  it('does not record analyzeExpression diagnostics by default', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.analyzeExpression({ expression: '(', cstType: CstType.TERM }, session.sessionId);
+    expect(tool.listDiagnostics(undefined, session.sessionId)).toHaveLength(0);
+  });
+
+  it('records analyzeExpression diagnostics when requested', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.analyzeExpression({ expression: '(', cstType: CstType.TERM, recordDiagnostics: true }, session.sessionId);
+    expect(tool.listDiagnostics(undefined, session.sessionId).length).toBeGreaterThan(0);
+  });
+
+  it('applySchemaPatch rolls back in atomic mode', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch({ items: [{ alias: 'X1' }] }, session.sessionId);
+
+    const result = tool.applySchemaPatch(
+      {
+        mode: 'atomic',
+        items: [
+          { alias: 'D1', definitionFormal: '1+2' },
+          { alias: 'D2', definitionFormal: 'Pr1(MISSING)' }
+        ]
+      },
+      session.sessionId
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.applied).toHaveLength(0);
+    expect(fullState(tool, session.sessionId).items).toHaveLength(1);
+  });
+
+  it('applySchemaPatch applies valid drafts in best_effort mode', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch(
+      {
+        items: [{ alias: 'X1' }, { alias: 'S1', definitionFormal: 'ℬ(X1×X1)' }]
+      },
+      session.sessionId
+    );
+
+    const result = tool.applySchemaPatch(
+      {
+        mode: 'best_effort',
+        items: [
+          { alias: 'D1', definitionFormal: 'Pr1(S1)' },
+          { alias: 'D2', definitionFormal: 'Pr1(MISSING)' }
+        ]
+      },
+      session.sessionId
+    );
+
+    expect(result.applied).toHaveLength(1);
+    expect(result.failed).toHaveLength(1);
+    expect(fullState(tool, session.sessionId).items.map(item => item.alias)).toContain('D1');
+  });
+
+  it('imports portal details JSON', () => {
+    const tool = new RSToolAgent();
+    const payload = {
+      title: 'Kinship',
+      alias: 'KIN',
+      description: 'Example',
+      items: [
+        { id: 1, alias: 'X1', cst_type: CstType.BASE, definition_formal: '' },
+        { id: 2, alias: 'D1', cst_type: CstType.TERM, definition_formal: '1+2' }
+      ]
+    };
+    const session = tool.importData(payload, 'portal-details');
+    const state = fullState(tool, session.sessionId);
+    expect(state.title).toBe('Kinship');
+    expect(state.items).toHaveLength(2);
+    expect(state.items.map(item => item.alias).sort()).toEqual(['D1', 'X1']);
+  });
+
+  it('auto-detects portal details import kind', () => {
+    const tool = new RSToolAgent();
+    const session = tool.importData({
+      title: 'Auto',
+      items: [{ id: 1, alias: 'X1', cst_type: CstType.BASE, definition_formal: '' }]
+    });
+    expect(fullState(tool, session.sessionId).title).toBe('Auto');
+  });
+
+  it('persists sessions across agent restarts', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'rstool-test-sessions-'));
+    try {
+      const tool = new RSToolAgent({ persistenceDir: dir });
+      const session = tool.createSession({ title: 'Persisted' });
+      tool.applySchemaPatch({ items: [{ alias: 'X1' }] }, session.sessionId);
+
+      const restored = new RSToolAgent({ persistenceDir: dir });
+      expect(restored.getCurrentSession()?.sessionId).toBe(session.sessionId);
+      expect(fullState(restored, session.sessionId).items).toHaveLength(1);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});