@principal-ai/subsystems-core 0.29.0

package/src/EventProcessor.test.ts

@@ -0,0 +1,405 @@
+import { EventProcessor } from './EventProcessor';
+import type { GraphConfiguration, GraphEvent } from './types';
+
+describe('EventProcessor', () => {
+  let testConfig: GraphConfiguration;
+
+  beforeEach(() => {
+    testConfig = {
+      metadata: {
+        name: 'Test System',
+        version: '1.0.0',
+      },
+      nodeTypes: {
+        user: {
+          shape: 'circle',
+          color: '#4CAF50',
+          dataSchema: {
+            userId: { type: 'string', required: true },
+            status: { type: 'string' },
+          },
+          states: {
+            online: { color: '#4CAF50', label: 'Online' },
+            offline: { color: '#9E9E9E', label: 'Offline' },
+          },
+        },
+        server: {
+          shape: 'hexagon',
+          color: '#9C27B0',
+          dataSchema: {
+            uptime: { type: 'number' },
+          },
+        },
+      },
+      edgeTypes: {
+        connection: {
+          style: 'solid',
+          directed: true,
+        },
+      },
+      allowedConnections: [{ from: 'user', to: 'server', via: 'connection' }],
+    };
+  });
+
+  describe('Node Events', () => {
+    it('should create a node', () => {
+      const processor = new EventProcessor(testConfig);
+
+      const event: GraphEvent = {
+        id: 'evt-1',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'user-1',
+          nodeType: 'user',
+          data: { userId: 'alice', status: 'online' },
+        },
+        expected: true,
+      };
+
+      const result = processor.processEvent(event);
+
+      expect(result.success).toBe(true);
+      expect(result.state.nodes.has('user-1')).toBe(true);
+
+      const node = result.state.nodes.get('user-1');
+      expect(node?.type).toBe('user');
+      expect(node?.data.userId).toBe('alice');
+    });
+
+    it('should update a node', () => {
+      const processor = new EventProcessor(testConfig);
+
+      // Create node first
+      processor.processEvent({
+        id: 'evt-1',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'user-1',
+          nodeType: 'user',
+          data: { userId: 'alice', status: 'offline' },
+        },
+        expected: true,
+      });
+
+      // Update node
+      const result = processor.processEvent({
+        id: 'evt-2',
+        type: 'node_updated',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'update',
+        payload: {
+          operation: 'update',
+          nodeId: 'user-1',
+          nodeType: 'user',
+          data: { status: 'online' },
+        },
+        expected: true,
+      });
+
+      expect(result.success).toBe(true);
+      const node = result.state.nodes.get('user-1');
+      expect(node?.data.status).toBe('online');
+      expect(node?.data.userId).toBe('alice'); // Should preserve existing data
+    });
+
+    it('should delete a node', () => {
+      const processor = new EventProcessor(testConfig);
+
+      // Create node first
+      processor.processEvent({
+        id: 'evt-1',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'user-1',
+          nodeType: 'user',
+          data: { userId: 'alice' },
+        },
+        expected: true,
+      });
+
+      // Delete node
+      const result = processor.processEvent({
+        id: 'evt-2',
+        type: 'node_deleted',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'delete',
+        payload: {
+          operation: 'delete',
+          nodeId: 'user-1',
+          nodeType: 'user',
+        },
+        expected: true,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.state.nodes.has('user-1')).toBe(false);
+    });
+  });
+
+  describe('Edge Events', () => {
+    it('should create an edge', () => {
+      const processor = new EventProcessor(testConfig);
+
+      // Create nodes first
+      processor.processEvent({
+        id: 'evt-1',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'user-1',
+          nodeType: 'user',
+          data: { userId: 'alice' },
+        },
+        expected: true,
+      });
+
+      processor.processEvent({
+        id: 'evt-2',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'server-1',
+          nodeType: 'server',
+          data: { uptime: 0 },
+        },
+        expected: true,
+      });
+
+      // Create edge
+      const result = processor.processEvent({
+        id: 'evt-3',
+        type: 'edge_created',
+        timestamp: Date.now(),
+        category: 'edge',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          edgeId: 'conn-1',
+          edgeType: 'connection',
+          from: 'user-1',
+          to: 'server-1',
+        },
+        expected: true,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.state.edges.has('conn-1')).toBe(true);
+
+      const edge = result.state.edges.get('conn-1');
+      expect(edge?.from).toBe('user-1');
+      expect(edge?.to).toBe('server-1');
+      expect(edge?.type).toBe('connection');
+    });
+
+    it('should delete an edge', () => {
+      const processor = new EventProcessor(testConfig);
+
+      // Create nodes and edge first
+      processor.processEvent({
+        id: 'evt-1',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'user-1',
+          nodeType: 'user',
+          data: { userId: 'alice' },
+        },
+        expected: true,
+      });
+
+      processor.processEvent({
+        id: 'evt-2',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'server-1',
+          nodeType: 'server',
+          data: { uptime: 0 },
+        },
+        expected: true,
+      });
+
+      processor.processEvent({
+        id: 'evt-3',
+        type: 'edge_created',
+        timestamp: Date.now(),
+        category: 'edge',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          edgeId: 'conn-1',
+          edgeType: 'connection',
+          from: 'user-1',
+          to: 'server-1',
+        },
+        expected: true,
+      });
+
+      // Delete edge
+      const result = processor.processEvent({
+        id: 'evt-4',
+        type: 'edge_deleted',
+        timestamp: Date.now(),
+        category: 'edge',
+        operation: 'delete',
+        payload: {
+          operation: 'delete',
+          edgeId: 'conn-1',
+          edgeType: 'connection',
+          from: 'user-1',
+          to: 'server-1',
+        },
+        expected: true,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.state.edges.has('conn-1')).toBe(false);
+    });
+  });
+
+  describe('State Events', () => {
+    it('should update node state', () => {
+      const processor = new EventProcessor(testConfig);
+
+      // Create node first
+      processor.processEvent({
+        id: 'evt-1',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'user-1',
+          nodeType: 'user',
+          data: { userId: 'alice' },
+        },
+        expected: true,
+      });
+
+      // Update state
+      const result = processor.processEvent({
+        id: 'evt-2',
+        type: 'state_changed',
+        timestamp: Date.now(),
+        category: 'state',
+        operation: 'update',
+        payload: {
+          nodeId: 'user-1',
+          newState: 'online',
+        },
+        expected: true,
+      });
+
+      expect(result.success).toBe(true);
+      const node = result.state.nodes.get('user-1');
+      expect(node?.state).toBe('online');
+    });
+  });
+
+  describe('System Events', () => {
+    it('should reset the graph state', () => {
+      const processor = new EventProcessor(testConfig);
+
+      // Create some nodes
+      processor.processEvent({
+        id: 'evt-1',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'user-1',
+          nodeType: 'user',
+          data: { userId: 'alice' },
+        },
+        expected: true,
+      });
+
+      // Reset
+      const result = processor.processEvent({
+        id: 'evt-2',
+        type: 'system_reset',
+        timestamp: Date.now(),
+        category: 'system',
+        operation: 'update',
+        payload: {
+          action: 'reset',
+        },
+        expected: true,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.state.nodes.size).toBe(0);
+      expect(result.state.edges.size).toBe(0);
+    });
+  });
+
+  describe('Event History', () => {
+    it('should track event history', () => {
+      const processor = new EventProcessor(testConfig);
+
+      processor.processEvent({
+        id: 'evt-1',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'user-1',
+          nodeType: 'user',
+          data: { userId: 'alice' },
+        },
+        expected: true,
+      });
+
+      processor.processEvent({
+        id: 'evt-2',
+        type: 'node_created',
+        timestamp: Date.now(),
+        category: 'node',
+        operation: 'create',
+        payload: {
+          operation: 'create',
+          nodeId: 'user-2',
+          nodeType: 'user',
+          data: { userId: 'bob' },
+        },
+        expected: true,
+      });
+
+      const history = processor.getEventHistory();
+      expect(history).toHaveLength(2);
+      expect(history[0].id).toBe('evt-1');
+      expect(history[1].id).toBe('evt-2');
+    });
+  });
+});

package/src/EventProcessor.ts

@@ -0,0 +1,256 @@
+import type {
+  GraphEvent,
+  GraphConfiguration,
+  GraphState,
+  ValidationResult,
+  NodeState,
+  EdgeState,
+  NodeEvent,
+  EdgeEvent,
+  StateEvent,
+  DataEvent,
+  SystemEvent,
+} from './types';
+import { ValidationEngine } from './ValidationEngine';
+import { ConfigurationValidator } from './ConfigurationValidator';
+
+export interface ProcessingResult {
+  success: boolean;
+  state: GraphState;
+  validation: ValidationResult;
+  error?: string;
+}
+
+/**
+ * EventProcessor handles the ingestion and processing of graph events
+ */
+export class EventProcessor {
+  private state: GraphState;
+  private validationEngine: ValidationEngine;
+  private eventHistory: GraphEvent[] = [];
+
+  constructor(configuration: GraphConfiguration, options?: { validateConfig?: boolean }) {
+    // Validate configuration by default (can be disabled for performance)
+    if (options?.validateConfig !== false) {
+      ConfigurationValidator.validateOrThrow(configuration);
+    }
+
+    this.state = {
+      nodes: new Map<string, NodeState>(),
+      edges: new Map<string, EdgeState>(),
+      configuration,
+    };
+    this.validationEngine = new ValidationEngine(configuration.validation || {});
+  }
+
+  /**
+   * Process a single graph event
+   */
+  processEvent(event: GraphEvent): ProcessingResult {
+    try {
+      // Validate event first
+      const validation = this.validateEvent(event);
+
+      // Apply the event to state
+      this.applyEvent(event);
+
+      // Store in history
+      this.eventHistory.push(event);
+
+      return {
+        success: true,
+        state: this.state,
+        validation,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        state: this.state,
+        validation: {
+          valid: false,
+          violations: [],
+          warnings: [],
+          metrics: this.getEmptyMetrics(),
+        },
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  /**
+   * Validate an event against configuration rules
+   */
+  validateEvent(event: GraphEvent): ValidationResult {
+    return this.validationEngine.validate(event, this.state);
+  }
+
+  /**
+   * Get the current graph state
+   */
+  getGraphState(): GraphState {
+    return this.state;
+  }
+
+  /**
+   * Get event history
+   */
+  getEventHistory(): GraphEvent[] {
+    return [...this.eventHistory];
+  }
+
+  /**
+   * Reset processor state
+   */
+  reset(): void {
+    this.state.nodes.clear();
+    this.state.edges.clear();
+    this.eventHistory = [];
+  }
+
+  /**
+   * Apply event to internal state
+   */
+  private applyEvent(event: GraphEvent): void {
+    const timestamp = event.timestamp;
+
+    switch (event.category) {
+      case 'node':
+        this.handleNodeEvent(event, timestamp);
+        break;
+      case 'edge':
+        this.handleEdgeEvent(event, timestamp);
+        break;
+      case 'state':
+        this.handleStateEvent(event, timestamp);
+        break;
+      case 'data':
+        this.handleDataEvent(event);
+        break;
+      case 'system':
+        this.handleSystemEvent(event);
+        break;
+    }
+  }
+
+  private handleNodeEvent(event: GraphEvent, timestamp: number): void {
+    const payload = event.payload as NodeEvent;
+
+    switch (payload.operation) {
+      case 'create':
+        this.state.nodes.set(payload.nodeId, {
+          id: payload.nodeId,
+          type: payload.nodeType,
+          name: typeof payload.data?.name === 'string' ? payload.data.name : payload.nodeId,
+          data: payload.data || {},
+          position: payload.position,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        });
+        break;
+      case 'update': {
+        const existingNode = this.state.nodes.get(payload.nodeId);
+        if (existingNode) {
+          this.state.nodes.set(payload.nodeId, {
+            ...existingNode,
+            data: { ...existingNode.data, ...payload.data },
+            position: payload.position || existingNode.position,
+            updatedAt: timestamp,
+          });
+        }
+        break;
+      }
+      case 'delete':
+        this.state.nodes.delete(payload.nodeId);
+        break;
+    }
+  }
+
+  private handleEdgeEvent(event: GraphEvent, timestamp: number): void {
+    const payload = event.payload as EdgeEvent;
+
+    switch (payload.operation) {
+      case 'create':
+        this.state.edges.set(payload.edgeId, {
+          id: payload.edgeId,
+          type: payload.edgeType,
+          from: payload.from,
+          to: payload.to,
+          data: payload.data,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        });
+        break;
+      case 'update': {
+        const existingEdge = this.state.edges.get(payload.edgeId);
+        if (existingEdge) {
+          this.state.edges.set(payload.edgeId, {
+            ...existingEdge,
+            data: { ...existingEdge.data, ...payload.data },
+            updatedAt: timestamp,
+          });
+        }
+        break;
+      }
+      case 'delete':
+        this.state.edges.delete(payload.edgeId);
+        break;
+      case 'animate':
+        // Animation is handled by the UI layer
+        break;
+    }
+  }
+
+  private handleStateEvent(event: GraphEvent, timestamp: number): void {
+    const payload = event.payload as StateEvent;
+    const node = this.state.nodes.get(payload.nodeId);
+    if (node) {
+      this.state.nodes.set(payload.nodeId, {
+        ...node,
+        state: payload.newState,
+        data: { ...node.data, ...payload.data },
+        updatedAt: timestamp,
+      });
+    }
+  }
+
+  private handleDataEvent(event: GraphEvent): void {
+    const payload = event.payload as DataEvent;
+    if (payload.targetType === 'node') {
+      const node = this.state.nodes.get(payload.targetId);
+      if (node) {
+        this.state.nodes.set(payload.targetId, {
+          ...node,
+          data: { ...node.data, ...payload.updates },
+          updatedAt: event.timestamp,
+        });
+      }
+    } else {
+      const edge = this.state.edges.get(payload.targetId);
+      if (edge) {
+        this.state.edges.set(payload.targetId, {
+          ...edge,
+          data: { ...edge.data, ...payload.updates },
+          updatedAt: event.timestamp,
+        });
+      }
+    }
+  }
+
+  private handleSystemEvent(event: GraphEvent): void {
+    const payload = event.payload as SystemEvent;
+    if (payload.action === 'reset') {
+      this.reset();
+    }
+  }
+
+  private getEmptyMetrics() {
+    return {
+      totalEvents: 0,
+      validEvents: 0,
+      violations: 0,
+      warnings: 0,
+      unexpectedEvents: 0,
+      expectedEventsMissing: 0,
+    };
+  }
+}