@rsconcept/rstool 1.0.0 → 1.0.1

package/src/models/agent-workflow.ts

@@ -1,10 +1,5 @@
 import { type CstType } from './common';
-import {
-  type ApplyConstituentsMode,
-  type ApplyConstituentsResult,
-  type ConstituentaDraft,
-  type ConstituentaState
-} from './constituenta';
+import { type ApplyConstituentsMode, type ApplyConstituentsResult, type ConstituentaDraft } from './constituenta';
 import { type DiagnosticRecord } from './diagnostic';
 import { type SessionHandle, type SessionRevision, type SessionState } from './session';
 
@@ -69,10 +64,3 @@ export interface ApplySchemaPatchResult extends ApplyConstituentsResult {
   summary: SessionSummary;
   revision?: SessionRevision;
 }
-
-/** Internal: resolved patch with previous state for undo bookkeeping. */
-export interface ResolvedAgentPatch {
-  patch: AgentConstituentaPatch;
-  draft: ConstituentaDraft;
-  previous?: ConstituentaState;
-}

package/src/models/import-detect.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+
+import { CstType } from './common';
+import { detectImportKind, parseImportPayload } from './import-detect';
+
+describe('parseImportPayload', () => {
+  it('parses JSON strings', () => {
+    expect(parseImportPayload('{"title":"x"}')).toEqual({ title: 'x' });
+  });
+
+  it('returns objects unchanged', () => {
+    const payload = { title: 'x' };
+    expect(parseImportPayload(payload)).toBe(payload);
+  });
+});
+
+describe('detectImportKind', () => {
+  it('detects session exports', () => {
+    expect(detectImportKind({ contractVersion: '2.0.0', state: { items: [] } })).toBe('session');
+  });
+
+  it('detects portal schema JSON', () => {
+    expect(
+      detectImportKind({
+        contract_version: '1.0.0',
+        items: [{ id: 1, alias: 'X1', cst_type: CstType.BASE }]
+      })
+    ).toBe('portal-schema');
+  });
+
+  it('detects portal details JSON', () => {
+    expect(
+      detectImportKind({
+        title: 'Schema',
+        items: [{ id: 1, alias: 'X1', cst_type: CstType.BASE }]
+      })
+    ).toBe('portal-details');
+  });
+
+  it('rejects model JSON as schema session', () => {
+    expect(() =>
+      detectImportKind({
+        contract_version: '1.0.0',
+        items: [{ id: 1, type: 'basic', value: { 0: 'a' } }]
+      })
+    ).toThrow(/Portal model JSON cannot be imported/);
+  });
+
+  it('treats empty contract_version items as undetectable', () => {
+    expect(() =>
+      detectImportKind({
+        contract_version: '1.0.0',
+        items: []
+      })
+    ).toThrow(/Cannot detect import kind/);
+  });
+
+  it('rejects non-objects', () => {
+    expect(() => detectImportKind(null)).toThrow(/Invalid import payload/);
+    expect(() => detectImportKind('string')).toThrow(/Invalid import payload/);
+  });
+
+  it('rejects undetectable payloads', () => {
+    expect(() => detectImportKind({ title: 'orphan' })).toThrow(/Cannot detect import kind/);
+  });
+});

package/src/models/import-detect.ts

@@ -22,10 +22,13 @@ export function detectImportKind(data: unknown): Exclude<ImportDataKind, 'auto'>
 
   if ('contract_version' in data && Array.isArray(data.items)) {
     const items = data.items as unknown[];
-    if (items.length > 0 && isRecord(items[0]) && 'cst_type' in items[0]) {
-      return 'portal-schema';
+    if (items.length > 0) {
+      const first = items[0];
+      if (isRecord(first) && 'cst_type' in first) {
+        return 'portal-schema';
+      }
+      throw new Error('Portal model JSON cannot be imported as a schema session');
     }
-    throw new Error('Portal model JSON cannot be imported as a schema session');
   }
 
   if (Array.isArray(data.items) && data.items.length > 0) {

package/src/models/portal-json.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { CstType } from './common';
+import { portalItemToDraft } from './portal-json';
+
+describe('portalItemToDraft', () => {
+  it('maps valid portal items', () => {
+    expect(
+      portalItemToDraft({
+        id: 1,
+        alias: 'D1',
+        cst_type: CstType.TERM,
+        definition_formal: '1+2',
+        term_raw: 'term',
+        definition_raw: 'def',
+        convention: 'conv'
+      })
+    ).toEqual({
+      id: 1,
+      alias: 'D1',
+      cstType: CstType.TERM,
+      definitionFormal: '1+2',
+      term: 'term',
+      definitionText: 'def',
+      convention: 'conv'
+    });
+  });
+
+  it('rejects unknown cst_type values', () => {
+    expect(() =>
+      portalItemToDraft({
+        id: 1,
+        alias: 'X1',
+        cst_type: 'not-a-cst-type'
+      })
+    ).toThrow(/Invalid cst_type "not-a-cst-type" for constituent "X1"/);
+  });
+});

package/src/models/portal-json.ts

@@ -1,6 +1,15 @@
-import { type BasicBinding, type RSToolValue } from './common';
+import { CstType, type BasicBinding, type RSToolValue } from './common';
 import { type ConstituentaDraft } from './constituenta';
 
+const CST_TYPE_VALUES = new Set<string>(Object.values(CstType));
+
+function parsePortalCstType(value: string, alias: string): ConstituentaDraft['cstType'] {
+  if (!CST_TYPE_VALUES.has(value)) {
+    throw new Error(`Invalid cst_type "${value}" for constituent "${alias}"`);
+  }
+  return value as ConstituentaDraft['cstType'];
+}
+
 /** Portal JSON import/export format version (schema and model files). */
 export const PORTAL_JSON_CONTRACT_VERSION = '1.0.0';
 
@@ -80,7 +89,7 @@ export function portalItemToDraft(item: {
   return {
     id: item.id,
     alias: item.alias,
-    cstType: item.cst_type as ConstituentaDraft['cstType'],
+    cstType: parsePortalCstType(item.cst_type, item.alias),
     definitionFormal: item.definition_formal ?? '',
     term: item.term_raw ?? '',
     definitionText: item.definition_raw ?? '',

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

@@ -1,8 +1,11 @@
-import { mkdtempSync, rmSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, rmSync, unlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { describe, expect, it } from 'vitest';
 
+import { TUPLE_ID } from '@rsconcept/domain';
+
 import { CstType, EvalStatus, RSErrorCode, RSToolAgent } from './index';
 
 function buildSampleForm(tool: RSToolAgent, sessionId: string) {
@@ -284,6 +287,37 @@ describe('RSToolAgent modeling and evaluation', () => {
     );
   });
 
+  it('restores session state when setModelValues fails mid-batch', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildSampleForm(tool, session.sessionId);
+    await tool.setModelValues({ set: [{ target: 1, value: { 0: 'a' } }] }, session.sessionId);
+
+    await expect(
+      tool.setModelValues(
+        {
+          set: [
+            { target: 1, value: { 0: 'b' } },
+            { target: 999, value: { 0: 'x' } }
+          ]
+        },
+        session.sessionId
+      )
+    ).rejects.toThrow(/Unknown constituent/);
+
+    expect(tool.getModelState(session.sessionId).items).toEqual([
+      expect.objectContaining({ id: 1, value: { 0: 'a' } })
+    ]);
+
+    await expect(
+      tool.setModelValues({ clear: [1], set: [{ target: 999, value: { 0: 'x' } }] }, session.sessionId)
+    ).rejects.toThrow(/Unknown constituent/);
+
+    expect(tool.getModelState(session.sessionId).items).toEqual([
+      expect.objectContaining({ id: 1, value: { 0: 'a' } })
+    ]);
+  });
+
   it('evaluates expression against session context', () => {
     const tool = new RSToolAgent();
     const session = tool.createSession();
@@ -416,8 +450,8 @@ describe('RSToolAgent agent ergonomics', () => {
     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]);
+    expect(fullState(tool).items.map(item => item.alias)).toEqual(['D1', 'X1', 'S1']);
+    expect(fullState(tool).items.map(item => item.cstType)).toEqual([CstType.TERM, CstType.BASE, CstType.STRUCTURED]);
   });
 
   it('exports Portal payloads as structured objects', () => {
@@ -549,3 +583,368 @@ describe('RSToolAgent agent ergonomics', () => {
     }
   });
 });
+
+describe('RSToolAgent session management', () => {
+  it('ensureSession reuses the current session', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession({ title: 'First' });
+    const ensured = tool.ensureSession({ title: 'Ignored' });
+    expect(ensured.sessionId).toBe(session.sessionId);
+    expect(fullState(tool).title).toBe('First');
+  });
+
+  it('ensureSession creates a session when none is active', () => {
+    const tool = new RSToolAgent();
+    expect(tool.getCurrentSession()).toBeNull();
+    const ensured = tool.ensureSession({ title: 'Created' });
+    expect(ensured.sessionId).toBeTruthy();
+    expect(fullState(tool).title).toBe('Created');
+  });
+
+  it('switches current session with setCurrentSession', () => {
+    const tool = new RSToolAgent();
+    const first = tool.createSession({ title: 'First' });
+    const second = tool.createSession({ title: 'Second' });
+    tool.setCurrentSession(first.sessionId);
+    expect(fullState(tool).title).toBe('First');
+    tool.setCurrentSession(second.sessionId);
+    expect(fullState(tool).title).toBe('Second');
+  });
+
+  it('throws when setCurrentSession receives an unknown id', () => {
+    const tool = new RSToolAgent();
+    const unknownId = randomUUID();
+    expect(() => tool.setCurrentSession(unknownId)).toThrow(/Unknown session/);
+  });
+
+  it('throws when an explicit unknown sessionId is passed to API methods', () => {
+    const tool = new RSToolAgent();
+    const unknownId = randomUUID();
+    expect(() => tool.getSessionState('full', unknownId)).toThrow(/Unknown session/);
+  });
+
+  it('applySchemaPatch with explicit sessionId does not switch current session', () => {
+    const tool = new RSToolAgent();
+    const first = tool.createSession({ title: 'First' });
+    const second = tool.createSession({ title: 'Second' });
+    tool.setCurrentSession(first.sessionId);
+
+    tool.applySchemaPatch({ items: [{ alias: 'X1' }] }, second.sessionId);
+
+    expect(tool.getCurrentSession()?.sessionId).toBe(first.sessionId);
+    expect(tool.getSessionState('summary', second.sessionId)).toMatchObject({ itemCount: 1 });
+    expect(tool.getSessionState('summary', first.sessionId)).toMatchObject({ itemCount: 0 });
+  });
+
+  it('returns summary session state by default', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession({ title: 'Summary', alias: 'SUM' });
+    tool.applySchemaPatch({ items: [{ alias: 'X1' }] }, session.sessionId);
+
+    const summary = tool.getSessionState('summary', session.sessionId);
+    expect(summary).toMatchObject({
+      sessionId: session.sessionId,
+      title: 'Summary',
+      alias: 'SUM',
+      itemCount: 1,
+      modelItemCount: 0
+    });
+    expect('items' in summary && summary.items[0]).toMatchObject({
+      alias: 'X1',
+      analysisSuccess: true
+    });
+  });
+
+  it('records revisions via commitStep', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch({ items: [{ alias: 'X1' }] }, session.sessionId);
+    const revision = tool.commitStep('checkpoint', session.sessionId);
+    expect(revision.message).toBe('checkpoint');
+    expect(fullState(tool, session.sessionId).revisions).toHaveLength(1);
+  });
+
+  it('filters diagnostics by constituent id', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch(
+      {
+        mode: 'best_effort',
+        items: [
+          { alias: 'X1', cstType: CstType.BASE, definitionFormal: 'Z' },
+          { alias: 'X2', cstType: CstType.BASE, definitionFormal: 'Z' }
+        ]
+      },
+      session.sessionId
+    );
+    const all = tool.listDiagnostics(undefined, session.sessionId);
+    const forX1 = tool.listDiagnostics({ constituentId: 1 }, session.sessionId);
+    expect(all.length).toBeGreaterThanOrEqual(2);
+    expect(forX1.every(record => record.constituentId === 1)).toBe(true);
+  });
+
+  it('filters diagnostics by constituent id 0', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch(
+      {
+        mode: 'best_effort',
+        items: [
+          { id: 0, alias: 'X0', cstType: CstType.BASE, definitionFormal: 'Z' },
+          { alias: 'X1', cstType: CstType.BASE, definitionFormal: 'Z' }
+        ]
+      },
+      session.sessionId
+    );
+    const all = tool.listDiagnostics(undefined, session.sessionId);
+    const forX0 = tool.listDiagnostics({ constituentId: 0 }, session.sessionId);
+    expect(all.length).toBeGreaterThanOrEqual(2);
+    expect(forX0.length).toBeGreaterThan(0);
+    expect(forX0.length).toBeLessThan(all.length);
+    expect(forX0.every(record => record.constituentId === 0)).toBe(true);
+  });
+
+  it('applySchemaPatch avoids id collisions when explicit ids precede auto-assigned ones', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch(
+      {
+        items: [
+          { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' },
+          { alias: 'X2', cstType: CstType.BASE, definitionFormal: '' }
+        ]
+      },
+      session.sessionId
+    );
+
+    const ids = fullState(tool, session.sessionId).items.map(item => item.id);
+    expect(ids).toEqual([1, 2]);
+  });
+
+  it('loads a persisted session from disk via setCurrentSession', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'rstool-test-sessions-'));
+    try {
+      const writer = new RSToolAgent({ persistenceDir: dir });
+      const session = writer.createSession({ title: 'On disk' });
+      writer.applySchemaPatch({ items: [{ alias: 'X1' }] }, session.sessionId);
+
+      const reader = new RSToolAgent({ persistenceDir: dir });
+      reader.setCurrentSession(session.sessionId);
+      expect(fullState(reader, session.sessionId).title).toBe('On disk');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('clears current session when persisted file is missing', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'rstool-test-sessions-'));
+    try {
+      const writer = new RSToolAgent({ persistenceDir: dir });
+      const session = writer.createSession({ title: 'Gone' });
+
+      unlinkSync(join(dir, `${session.sessionId}.json`));
+
+      const reader = new RSToolAgent({ persistenceDir: dir });
+      expect(reader.getCurrentSession()).toBeNull();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('RSToolAgent import and export', () => {
+  it('imports portal schema JSON', () => {
+    const tool = new RSToolAgent();
+    const payload = {
+      contract_version: '1.0.0',
+      title: 'Imported schema',
+      alias: 'IMP',
+      description: 'From portal',
+      items: [
+        { id: 1, alias: 'X1', cst_type: CstType.BASE, definition_formal: '' },
+        { id: 2, alias: 'D1', cst_type: CstType.TERM, definition_formal: '1+2' }
+      ],
+      attribution: []
+    };
+    const session = tool.importData(payload, 'portal-schema');
+    const state = fullState(tool, session.sessionId);
+    expect(state).toMatchObject({ title: 'Imported schema', alias: 'IMP', comment: 'From portal' });
+    expect(state.items.map(item => item.alias)).toEqual(['X1', 'D1']);
+  });
+
+  it('keeps declaration order in portal schema export', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession({ title: 'Order', alias: 'ORD' });
+    tool.applySchemaPatch(
+      {
+        items: [
+          { alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' },
+          { alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' },
+          { alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' },
+          { alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
+        ]
+      },
+      session.sessionId
+    );
+
+    const exported = tool.exportPortal({ kind: 'schema', format: 'object' }, session.sessionId) as {
+      items: Array<{ alias: string }>;
+    };
+    expect(exported.items.map(item => item.alias)).toEqual(['D1', 'S1', 'C1', 'X1']);
+  });
+
+  it('round-trips portal schema export and import', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession({ title: 'Round trip', alias: 'RT' });
+    tool.applySchemaPatch(
+      {
+        items: [{ alias: 'D1', cstType: CstType.TERM, definitionFormal: '1+2', term: 'sum' }]
+      },
+      session.sessionId
+    );
+
+    const exported = tool.exportPortal({ kind: 'schema', format: 'object' });
+    const imported = tool.importData(exported, 'portal-schema');
+    const state = fullState(tool, imported.sessionId);
+    expect(state.title).toBe('Round trip');
+    expect(state.items[0]).toMatchObject({
+      alias: 'D1',
+      definitionFormal: '1+2',
+      term: 'sum'
+    });
+  });
+
+  it('rejects invalid session export payloads', () => {
+    const tool = new RSToolAgent();
+    expect(() => tool.importData({ contractVersion: '2.0.0' }, 'session')).toThrow(/Invalid session export/);
+  });
+
+  it('rejects undetectable import payloads', () => {
+    const tool = new RSToolAgent();
+    expect(() => tool.importData({ title: 'orphan' })).toThrow(/Cannot detect import kind/);
+  });
+
+  it('infers cstType from N and T alias prefixes', () => {
+    const tool = new RSToolAgent();
+    const statementResult = tool.applySchemaPatch({ items: [{ alias: 'T1', definitionFormal: '1=1' }] });
+    expect(statementResult.success).toBe(true);
+    expect(fullState(tool).items[0]?.cstType).toBe(CstType.STATEMENT);
+
+    const nominalResult = tool.applySchemaPatch({ items: [{ alias: 'N1' }] });
+    expect(nominalResult.failed[0]?.draft.cstType).toBe(CstType.NOMINAL);
+  });
+
+  it('rejects aliases with unknown cstType prefix', () => {
+    const tool = new RSToolAgent();
+    expect(() =>
+      tool.applySchemaPatch({
+        items: [{ alias: 'Q1', definitionFormal: '1' }]
+      })
+    ).toThrow(/Cannot infer cstType/);
+  });
+});
+
+describe('RSToolAgent modeling semantics', () => {
+  function buildKinshipScratch(tool: RSToolAgent, sessionId: string) {
+    tool.applySchemaPatch(
+      {
+        items: [
+          { alias: 'X1' },
+          { alias: 'S1', definitionFormal: 'ℬ(X1×X1)' },
+          { alias: 'D1', definitionFormal: 'Pr1(S1)' },
+          { alias: 'A1', cstType: CstType.AXIOM, definitionFormal: 'card(X1)≤1' }
+        ]
+      },
+      sessionId
+    );
+  }
+
+  it('returns EMPTY when a basic set has no binding', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch({ items: [{ alias: 'X1' }] }, session.sessionId);
+
+    const result = tool.evaluate({ constituentId: 1 }, session.sessionId);
+    expect(result.status).toBe(EvalStatus.EMPTY);
+    expect(result.value).toBeNull();
+  });
+
+  it('sets structured set values and evaluates projections', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildKinshipScratch(tool, session.sessionId);
+
+    await tool.setModelValues(
+      {
+        set: [
+          { target: 1, value: { 0: 'ann', 1: 'bob' } },
+          {
+            target: 2,
+            value: [
+              [TUPLE_ID, 0, 1],
+              [TUPLE_ID, 1, 0]
+            ]
+          }
+        ]
+      },
+      session.sessionId
+    );
+
+    const result = tool.evaluate({ constituentId: 3 }, session.sessionId);
+    expect(result.success).toBe(true);
+    expect(result.status).toBe(EvalStatus.HAS_DATA);
+    expect(Array.isArray(result.value)).toBe(true);
+    expect((result.value as unknown[]).length).toBeGreaterThan(0);
+  });
+
+  it('reports AXIOM_FALSE when model data violates the axiom', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildKinshipScratch(tool, session.sessionId);
+
+    await tool.setModelValues({ set: [{ target: 1, value: { 0: 'ann', 1: 'bob' } }] }, session.sessionId);
+
+    const result = tool.evaluate({ constituentId: 4 }, session.sessionId);
+    expect(result.status).toBe(EvalStatus.AXIOM_FALSE);
+    expect(result.value).toBe(0);
+  });
+
+  it('reports AXIOM_FALSE via recalculateModel', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildKinshipScratch(tool, session.sessionId);
+    await tool.setModelValues({ set: [{ target: 1, value: { 0: 'ann', 1: 'bob' } }] }, session.sessionId);
+
+    const recalculated = tool.recalculateModel(session.sessionId);
+    const a1 = recalculated.items.find(item => item.alias === 'A1');
+    expect(a1?.status).toBe(EvalStatus.AXIOM_FALSE);
+    expect(a1?.value).toBe(0);
+  });
+
+  it('throws when evaluate input is incomplete', () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    expect(() => tool.evaluate({}, session.sessionId)).toThrow(/requires constituentId or expression/);
+  });
+
+  it('throws for unknown constituents on evaluate and setModelValues', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    buildSampleForm(tool, session.sessionId);
+
+    expect(() => tool.evaluate({ constituentId: 999 }, session.sessionId)).toThrow(/Unknown constituent/);
+    await expect(tool.setModelValues({ set: [{ target: 999, value: { 0: 'a' } }] }, session.sessionId)).rejects.toThrow(
+      /Unknown constituent/
+    );
+  });
+
+  it('rejects invalid basic binding data', async () => {
+    const tool = new RSToolAgent();
+    const session = tool.createSession();
+    tool.applySchemaPatch({ items: [{ alias: 'X1' }] }, session.sessionId);
+
+    await expect(
+      tool.setModelValues({ set: [{ target: 1, value: [1, 2, 3] as never }] }, session.sessionId)
+    ).rejects.toThrow(/Invalid basic binding/);
+  });
+});