@rsconcept/rstool 1.0.0 → 1.0.1

package/src/models/rstool-agent.ts

@@ -6,7 +6,7 @@ import {
 } from '../mappers/portal-adapter';
 import { ModelAdapter } from '../mappers/model-adapter';
 import { SchemaAdapter } from '../mappers/schema-adapter';
-import { orderDrafts } from '../session/batch-apply';
+import { orderDrafts, reorderSessionItemsByDrafts } from '../session/batch-apply';
 import { SessionStore } from '../session/session-store';
 import {
   type AgentConstituentaPatch,
@@ -82,6 +82,10 @@ function inferCstType(alias: string): CstType {
       return CstType.FUNCTION;
     case 'P':
       return CstType.PREDICATE;
+    case 'N':
+      return CstType.NOMINAL;
+    case 'T':
+      return CstType.STATEMENT;
     default:
       throw new Error(`Cannot infer cstType from alias "${alias}"; pass cstType explicitly`);
   }
@@ -141,7 +145,9 @@ export class RSToolAgent implements RSToolAgentContract {
 
   /** @inheritdoc */
   public applySchemaPatch(input: ApplySchemaPatchInput, sessionId?: string): ApplySchemaPatchResult {
-    const session = sessionId ? this.setCurrentSession(sessionId) : this.ensureSession(input.initial);
+    const session = sessionId
+      ? { sessionId: this.resolveSessionId(sessionId), contractVersion: this.contractVersion }
+      : this.ensureSession(input.initial);
     const drafts = this.resolveAgentPatches(session.sessionId, input.items);
     const result = this.applyConstituents(
       {
@@ -241,23 +247,30 @@ export class RSToolAgent implements RSToolAgentContract {
   /** @inheritdoc */
   public async setModelValues(input: SetModelValuesInput, sessionId?: string): Promise<SessionModelState> {
     const id = this.resolveSessionId(sessionId);
-    let state = this.sessions.get(id).state;
+    const snapshot = this.sessions.snapshot(id);
 
-    if (input.clear?.length) {
-      const model = await this.evaluation.clearConstituentaValues(state, input.clear);
-      state = { ...state, model };
-      this.sessions.replaceState(id, state);
-    }
+    try {
+      let state = this.sessions.get(id).state;
 
-    if (input.set?.length) {
-      state = this.sessions.get(id).state;
-      const model = await this.evaluation.setConstituentaValues(state, { items: input.set });
-      state = { ...state, model };
-      this.sessions.replaceState(id, state);
-      return model;
-    }
+      if (input.clear?.length) {
+        const model = await this.evaluation.clearConstituentaValues(state, input.clear);
+        state = { ...state, model };
+        this.sessions.replaceState(id, state);
+      }
 
-    return structuredClone(this.sessions.get(id).state.model);
+      if (input.set?.length) {
+        state = this.sessions.get(id).state;
+        const model = await this.evaluation.setConstituentaValues(state, { items: input.set });
+        state = { ...state, model };
+        this.sessions.replaceState(id, state);
+        return model;
+      }
+
+      return structuredClone(this.sessions.get(id).state.model);
+    } catch (error) {
+      this.sessions.restore(id, snapshot);
+      throw error;
+    }
   }
 
   /** @inheritdoc */
@@ -325,6 +338,10 @@ export class RSToolAgent implements RSToolAgentContract {
       }
     }
 
+    const envelope = this.sessions.get(id);
+    reorderSessionItemsByDrafts(envelope.state.items, input.drafts);
+    this.sessions.replaceState(id, envelope.state);
+
     return {
       success: failed.length === 0,
       applied,
@@ -424,11 +441,37 @@ export class RSToolAgent implements RSToolAgentContract {
   private resolveAgentPatches(sessionId: string, patches: AgentConstituentaPatch[]): ConstituentaDraft[] {
     const items = this.sessions.get(sessionId).state.items;
     const existingByAlias = new Map(items.map(item => [item.alias, item]));
+    const usedIds = new Set(items.map(item => item.id));
     let nextId = items.reduce((max, item) => Math.max(max, item.id), 0) + 1;
 
+    const reserveId = (id: number): void => {
+      usedIds.add(id);
+      if (id >= nextId) {
+        nextId = id + 1;
+      }
+    };
+
+    const allocateId = (): number => {
+      while (usedIds.has(nextId)) {
+        nextId += 1;
+      }
+      const id = nextId;
+      nextId += 1;
+      usedIds.add(id);
+      return id;
+    };
+
     return patches.map(patch => {
       const existing = existingByAlias.get(patch.alias);
-      const id = patch.id ?? existing?.id ?? nextId++;
+      let id: number;
+      if (patch.id !== undefined) {
+        id = patch.id;
+        reserveId(id);
+      } else if (existing !== undefined) {
+        id = existing.id;
+      } else {
+        id = allocateId();
+      }
       const draft = {
         id,
         alias: patch.alias,

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

@@ -1,28 +1,123 @@
 import { describe, expect, it } from 'vitest';
 
 import { CstType } from '../models';
-import { orderDrafts } from './batch-apply';
+import { orderDrafts, reorderSessionItemsByDrafts } from './batch-apply';
+
+const baseItem = {
+  id: 1,
+  alias: 'X1',
+  cstType: CstType.BASE,
+  definitionFormal: '',
+  term: '',
+  definitionText: '',
+  convention: '',
+  analysis: { success: true, type: null, valueClass: 'value' as const, diagnostics: [] }
+};
 
 describe('orderDrafts', () => {
   it('orders dependents after suppliers', () => {
     const ordered = orderDrafts(
+      [baseItem],
+      [
+        { 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']);
+  });
+
+  it('orders multi-hop chains X1 → S1 → D1', () => {
+    const ordered = orderDrafts(
+      [baseItem],
       [
+        { id: 4, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' },
+        { id: 3, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' },
+        { id: 2, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' }
+      ]
+    );
+    expect(ordered.map(draft => draft.alias)).toEqual(['C1', 'S1', 'D1']);
+  });
+
+  it('orders draft that only references existing session items', () => {
+    const ordered = orderDrafts(
+      [
+        baseItem,
         {
-          id: 1,
-          alias: 'X1',
-          cstType: CstType.BASE,
-          definitionFormal: '',
+          id: 2,
+          alias: 'S1',
+          cstType: CstType.STRUCTURED,
+          definitionFormal: 'ℬ(X1×X1)',
           term: '',
           definitionText: '',
           convention: '',
           analysis: { success: true, type: null, valueClass: 'value', diagnostics: [] }
         }
       ],
+      [{ id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }]
+    );
+    expect(ordered.map(draft => draft.alias)).toEqual(['D1']);
+  });
+
+  it('appends cyclic drafts after topological ids', () => {
+    const ordered = orderDrafts(
+      [],
       [
-        { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' },
-        { id: 2, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' }
+        { id: 1, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'D2' },
+        { id: 2, alias: 'D2', cstType: CstType.TERM, definitionFormal: 'D1' }
       ]
     );
-    expect(ordered.map(draft => draft.alias)).toEqual(['S1', 'D1']);
+    expect(ordered.map(draft => draft.alias).sort()).toEqual(['D1', 'D2']);
+    expect(ordered).toHaveLength(2);
+  });
+
+  it('returns all independent drafts', () => {
+    const ordered = orderDrafts(
+      [],
+      [
+        { id: 1, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' },
+        { id: 2, alias: 'C2', cstType: CstType.CONSTANT, definitionFormal: '' }
+      ]
+    );
+    expect(ordered.map(draft => draft.alias).sort()).toEqual(['C1', 'C2']);
+    expect(ordered).toHaveLength(2);
+  });
+});
+
+describe('reorderSessionItemsByDrafts', () => {
+  const mk = (id: number, alias: string) => ({
+    id,
+    alias,
+    cstType: CstType.BASE,
+    definitionFormal: '',
+    term: '',
+    definitionText: '',
+    convention: '',
+    analysis: { success: true, type: null, valueClass: 'value' as const, diagnostics: [] }
+  });
+
+  it('restores full-batch declaration order', () => {
+    const items = [mk(4, 'X1'), mk(3, 'C1'), mk(2, 'S1'), mk(1, 'D1')];
+    reorderSessionItemsByDrafts(items, [
+      { id: 1, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' },
+      { id: 2, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' },
+      { id: 3, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' },
+      { id: 4, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
+    ]);
+    expect(items.map(item => item.alias)).toEqual(['D1', 'S1', 'C1', 'X1']);
+  });
+
+  it('appends only new items in draft order', () => {
+    const items = [mk(1, 'X1'), mk(3, 'S1'), mk(2, 'C1')];
+    reorderSessionItemsByDrafts(items, [
+      { id: 2, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' },
+      { id: 3, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' }
+    ]);
+    expect(items.map(item => item.alias)).toEqual(['X1', 'C1', 'S1']);
+  });
+
+  it('does not move existing items on update-only patch', () => {
+    const items = [mk(1, 'X1'), mk(2, 'D1')];
+    reorderSessionItemsByDrafts(items, [{ id: 2, alias: 'D1', cstType: CstType.TERM, definitionFormal: '1+2' }]);
+    expect(items.map(item => item.alias)).toEqual(['X1', 'D1']);
   });
 });

package/src/session/batch-apply.ts

@@ -45,3 +45,38 @@ export function orderDrafts(sessionItems: ConstituentaState[], drafts: Constitue
   const orderedIds = [...topoIds, ...missing];
   return orderedIds.map(id => drafts.find(draft => draft.id === id)!).filter(Boolean);
 }
+
+/**
+ * Restore declaration order in session items after a batch apply.
+ * Topological apply order is only needed for analysis; Portal JSON uses array order.
+ */
+export function reorderSessionItemsByDrafts(items: ConstituentaState[], drafts: ConstituentaDraft[]): void {
+  if (drafts.length === 0 || items.length === 0) {
+    return;
+  }
+
+  const draftIds = drafts.map(draft => draft.id);
+  const draftIdSet = new Set(draftIds);
+  const mentioned = items.filter(item => draftIdSet.has(item.id));
+  if (mentioned.length === 0) {
+    return;
+  }
+
+  const unmentioned = items.filter(item => !draftIdSet.has(item.id));
+  if (unmentioned.length === 0) {
+    const byId = new Map(items.map(item => [item.id, item]));
+    items.splice(0, items.length, ...draftIds.map(id => byId.get(id)!));
+    return;
+  }
+
+  const existingIds = new Set(unmentioned.map(item => item.id));
+  const newDrafts = drafts.filter(draft => !existingIds.has(draft.id));
+  if (newDrafts.length === 0) {
+    return;
+  }
+
+  const newIds = new Set(newDrafts.map(draft => draft.id));
+  const kept = items.filter(item => !newIds.has(item.id));
+  const byId = new Map(items.map(item => [item.id, item]));
+  items.splice(0, items.length, ...kept, ...newDrafts.map(draft => byId.get(draft.id)!));
+}

package/src/session/persistence.test.ts

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { SessionPersistence, type PersistedSessionEnvelope } from './persistence';
+
+const envelope: PersistedSessionEnvelope = {
+  state: {
+    sessionId: 'safe-id',
+    alias: '',
+    title: '',
+    comment: '',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    revisions: [],
+    items: [],
+    model: { items: [] }
+  },
+  diagnostics: []
+};
+
+describe('SessionPersistence', () => {
+  const dirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of dirs.splice(0)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  function createPersistence(): SessionPersistence {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rstool-session-'));
+    dirs.push(dir);
+    return new SessionPersistence(dir);
+  }
+
+  it('persists a safe session id under the configured directory', () => {
+    const persistence = createPersistence();
+    const sessionId = 'a03eec4c-6519-4088-9d8c-0a9c11611583';
+
+    persistence.save(sessionId, envelope);
+
+    expect(persistence.load(sessionId)).toEqual(envelope);
+    persistence.delete(sessionId);
+    expect(persistence.load(sessionId)).toBeNull();
+  });
+
+  it.each(['../escape', 'foo/bar', 'foo\\bar', '..', 'safe/../escape'])(
+    'rejects unsafe session id %j on save',
+    unsafeId => {
+      const persistence = createPersistence();
+      expect(() => persistence.save(unsafeId, envelope)).toThrow(/Invalid session ID/);
+    }
+  );
+
+  it.each(['../escape', 'foo/bar', 'foo\\bar', '..'])('rejects unsafe session id %j on load and delete', unsafeId => {
+    const persistence = createPersistence();
+    expect(() => persistence.load(unsafeId)).toThrow(/Invalid session ID/);
+    expect(() => persistence.delete(unsafeId)).toThrow(/Invalid session ID/);
+  });
+});

package/src/session/persistence.ts

@@ -9,6 +9,13 @@ export interface PersistedSessionEnvelope {
 }
 
 const CURRENT_SESSION_FILE = '_current.json';
+const UNSAFE_SESSION_ID = /[/\\]|\.\./;
+
+function assertSafeSessionId(sessionId: string): void {
+  if (!sessionId || UNSAFE_SESSION_ID.test(sessionId)) {
+    throw new Error(`Invalid session ID: ${sessionId}`);
+  }
+}
 
 export class SessionPersistence {
   private readonly dir: string;
@@ -51,6 +58,12 @@ export class SessionPersistence {
   }
 
   private filePath(sessionId: string): string {
-    return path.join(this.dir, `${sessionId}.json`);
+    assertSafeSessionId(sessionId);
+    const file = path.resolve(this.dir, `${sessionId}.json`);
+    const relative = path.relative(path.resolve(this.dir), file);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new Error(`Invalid session ID: ${sessionId}`);
+    }
+    return file;
   }
 }

package/src/session/session-store.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 
 import {
+  CONTRACT_VERSION,
   type DiagnosticRecord,
   type ListDiagnosticsFilters,
   type SessionHandle,
@@ -48,7 +49,7 @@ export class SessionStore {
     this.persist(sessionId, envelope);
     return {
       sessionId,
-      contractVersion: contractVersion ?? '1.0.0'
+      contractVersion: contractVersion ?? CONTRACT_VERSION
     };
   }
 
@@ -61,7 +62,13 @@ export class SessionStore {
   }
 
   public has(sessionId: string): boolean {
-    return this.sessions.has(sessionId) || this.persistence?.load(sessionId) !== null;
+    if (this.sessions.has(sessionId)) {
+      return true;
+    }
+    if (!this.persistence) {
+      return false;
+    }
+    return this.persistence.load(sessionId) !== null;
   }
 
   public replaceState(sessionId: string, nextState: SessionState): void {
@@ -108,7 +115,7 @@ export class SessionStore {
 
   public listDiagnostics(sessionId: string, filters?: ListDiagnosticsFilters): DiagnosticRecord[] {
     const found = this.get(sessionId);
-    if (!filters?.constituentId) {
+    if (filters?.constituentId === undefined) {
       return [...found.diagnostics];
     }
     return found.diagnostics.filter(record => record.constituentId === filters.constituentId);

package/src/wrapper/client.test.ts

@@ -0,0 +1,58 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+import { CstType, EvalStatus, RSToolWrapperClient } from '../index';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+describe('RSToolWrapperClient integration', () => {
+  it('runs createSession, patch, model, and evaluate over stdio', async () => {
+    const client = new RSToolWrapperClient({
+      command: 'npx',
+      args: ['tsx', resolve(packageRoot, 'src/wrapper/stdio-wrapper.ts')],
+      cwd: packageRoot,
+      shell: true
+    });
+
+    try {
+      await client.waitUntilReady();
+
+      const methods = await client.call<string[]>('methods');
+      expect(methods).toContain('applySchemaPatch');
+
+      const session = await client.call<{ sessionId: string; contractVersion: string }>('createSession', {
+        initial: { title: 'Wrapper test' }
+      });
+      expect(session.sessionId).toBeTruthy();
+
+      await client.call('applySchemaPatch', {
+        sessionId: session.sessionId,
+        items: [{ alias: 'X1' }, { alias: 'D1', definitionFormal: '1+2' }]
+      });
+
+      await client.call('setModelValues', {
+        sessionId: session.sessionId,
+        set: [{ target: 1, value: { 0: 'zero' } }]
+      });
+
+      const evalResult = await client.call<{ success: boolean; value: number; status: number }>('evaluate', {
+        sessionId: session.sessionId,
+        constituentId: 2
+      });
+      expect(evalResult.success).toBe(true);
+      expect(evalResult.value).toBe(3);
+      expect(evalResult.status).toBe(EvalStatus.HAS_DATA);
+
+      const analysis = await client.call<{ success: boolean; diagnostics: unknown[] }>('analyzeExpression', {
+        sessionId: session.sessionId,
+        expression: '(',
+        cstType: CstType.TERM
+      });
+      expect(analysis.success).toBe(false);
+      expect(analysis.diagnostics.length).toBeGreaterThan(0);
+    } finally {
+      await client.close();
+    }
+  }, 30_000);
+});

package/src/wrapper/stdio-handler.test.ts

@@ -0,0 +1,101 @@
+import { randomUUID } from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+
+import { CstType, CONTRACT_VERSION, RSToolAgent } from '../models';
+import { handleStdioRequest, STDIO_METHODS } from './stdio-handler';
+
+describe('handleStdioRequest', () => {
+  const tool = new RSToolAgent();
+
+  it('responds to ping with contract version', async () => {
+    const response = await handleStdioRequest(tool, { id: 1, method: 'ping' });
+    expect(response).toEqual({
+      id: 1,
+      ok: true,
+      result: { pong: true, contractVersion: CONTRACT_VERSION }
+    });
+  });
+
+  it('lists contract methods', async () => {
+    const response = await handleStdioRequest(tool, { id: 2, method: 'methods' });
+    expect(response.ok).toBe(true);
+    expect(response.result).toEqual(STDIO_METHODS);
+  });
+
+  it('applies schema patch through the wrapper', async () => {
+    const response = await handleStdioRequest(tool, {
+      id: 3,
+      method: 'applySchemaPatch',
+      params: { items: [{ alias: 'X1' }] }
+    });
+    expect(response.ok).toBe(true);
+    expect((response.result as { success: boolean }).success).toBe(true);
+  });
+
+  it('evaluates a constituent', async () => {
+    const sessionTool = new RSToolAgent();
+    await handleStdioRequest(sessionTool, {
+      id: 10,
+      method: 'applySchemaPatch',
+      params: {
+        items: [{ alias: 'X1' }, { alias: 'D1', definitionFormal: '1+2' }]
+      }
+    });
+    const response = await handleStdioRequest(sessionTool, {
+      id: 11,
+      method: 'evaluate',
+      params: { constituentId: 2 }
+    });
+    expect(response.ok).toBe(true);
+    expect((response.result as { value: number }).value).toBe(3);
+  });
+
+  it('returns METHOD_NOT_FOUND for unknown methods', async () => {
+    const response = await handleStdioRequest(tool, { id: 4, method: 'notReal' });
+    expect(response.ok).toBe(false);
+    expect(response.error?.code).toBe('METHOD_NOT_FOUND');
+  });
+
+  it('returns INTERNAL_ERROR when setCurrentSession lacks sessionId', async () => {
+    const response = await handleStdioRequest(tool, { id: 5, method: 'setCurrentSession', params: {} });
+    expect(response.ok).toBe(false);
+    expect(response.error?.code).toBe('INTERNAL_ERROR');
+    expect(response.error?.message).toMatch(/sessionId/);
+  });
+
+  it('returns INTERNAL_ERROR for unknown session id', async () => {
+    const sessionTool = new RSToolAgent();
+    const response = await handleStdioRequest(sessionTool, {
+      id: 6,
+      method: 'setCurrentSession',
+      params: { sessionId: randomUUID() }
+    });
+    expect(response.ok).toBe(false);
+    expect(response.error?.code).toBe('INTERNAL_ERROR');
+    expect(response.error?.message).toMatch(/Unknown session/);
+  });
+
+  it('filters diagnostics by constituentId param', async () => {
+    const sessionTool = new RSToolAgent();
+    const created = await handleStdioRequest(sessionTool, { id: 20, method: 'createSession' });
+    const sessionId = (created.result as { sessionId: string }).sessionId;
+    await handleStdioRequest(sessionTool, {
+      id: 21,
+      method: 'applySchemaPatch',
+      params: {
+        sessionId,
+        mode: 'best_effort',
+        items: [{ alias: 'X1', cstType: CstType.BASE, definitionFormal: 'Z' }]
+      }
+    });
+
+    const all = await handleStdioRequest(sessionTool, { id: 22, method: 'listDiagnostics', params: { sessionId } });
+    const filtered = await handleStdioRequest(sessionTool, {
+      id: 23,
+      method: 'listDiagnostics',
+      params: { sessionId, constituentId: 1 }
+    });
+    expect((all.result as unknown[]).length).toBeGreaterThan(0);
+    expect(filtered.result).toEqual(all.result);
+  });
+});