@sparkleideas/shared 3.0.0-alpha.7

package/src/events/state-reconstructor.ts

@@ -0,0 +1,349 @@
+/**
+ * State Reconstructor - ADR-007 Implementation
+ *
+ * Reconstructs aggregate state from event streams.
+ * Implements event sourcing patterns for V3.
+ *
+ * @module v3/shared/events/state-reconstructor
+ */
+
+import { EventStore, type EventSnapshot } from './event-store.js';
+import type { DomainEvent } from './domain-events.js';
+
+/**
+ * Aggregate root interface
+ */
+export interface AggregateRoot {
+  id: string;
+  version: number;
+  apply(event: DomainEvent): void;
+  getState(): Record<string, unknown>;
+}
+
+/**
+ * Reconstructor options
+ */
+export interface ReconstructorOptions {
+  useSnapshots: boolean;
+  snapshotInterval: number; // Create snapshot every N events
+  maxEventsToReplay: number;
+}
+
+/**
+ * State Reconstructor
+ *
+ * Reconstructs aggregate state from event history.
+ * Supports snapshots for performance optimization.
+ */
+export class StateReconstructor {
+  private readonly options: ReconstructorOptions;
+
+  constructor(
+    private readonly eventStore: EventStore,
+    options?: Partial<ReconstructorOptions>
+  ) {
+    this.options = {
+      useSnapshots: true,
+      snapshotInterval: 100,
+      maxEventsToReplay: 10000,
+      ...options,
+    };
+  }
+
+  /**
+   * Reconstruct aggregate state from events
+   */
+  async reconstruct<T extends AggregateRoot>(
+    aggregateId: string,
+    factory: (id: string) => T
+  ): Promise<T> {
+    const aggregate = factory(aggregateId);
+
+    // Try to load from snapshot first
+    if (this.options.useSnapshots) {
+      const snapshot = await this.eventStore.getSnapshot(aggregateId);
+      if (snapshot) {
+        this.applySnapshot(aggregate, snapshot);
+      }
+    }
+
+    // Get events after snapshot version (or all if no snapshot)
+    const events = await this.eventStore.getEvents(aggregateId, aggregate.version + 1);
+
+    // Apply events
+    for (const event of events) {
+      if (events.length > this.options.maxEventsToReplay) {
+        throw new Error(`Too many events to replay (${events.length}). Consider creating a snapshot.`);
+      }
+
+      aggregate.apply(event);
+    }
+
+    // Create snapshot if interval reached
+    if (this.options.useSnapshots && aggregate.version % this.options.snapshotInterval === 0) {
+      await this.createSnapshot(aggregate);
+    }
+
+    return aggregate;
+  }
+
+  /**
+   * Reconstruct state at a specific point in time
+   */
+  async reconstructAtTime<T extends AggregateRoot>(
+    aggregateId: string,
+    factory: (id: string) => T,
+    timestamp: Date
+  ): Promise<T> {
+    const aggregate = factory(aggregateId);
+
+    // Get all events up to timestamp
+    const allEvents = await this.eventStore.getEvents(aggregateId);
+    const events = allEvents.filter((e) => e.timestamp <= timestamp.getTime());
+
+    // Apply events
+    for (const event of events) {
+      aggregate.apply(event);
+    }
+
+    return aggregate;
+  }
+
+  /**
+   * Reconstruct state at a specific version
+   */
+  async reconstructAtVersion<T extends AggregateRoot>(
+    aggregateId: string,
+    factory: (id: string) => T,
+    targetVersion: number
+  ): Promise<T> {
+    const aggregate = factory(aggregateId);
+
+    // Get events up to target version
+    const events = await this.eventStore.getEvents(aggregateId);
+    const limitedEvents = events.filter((e) => e.version <= targetVersion);
+
+    // Apply events
+    for (const event of limitedEvents) {
+      aggregate.apply(event);
+    }
+
+    return aggregate;
+  }
+
+  /**
+   * Apply snapshot to aggregate
+   */
+  private applySnapshot(aggregate: AggregateRoot, snapshot: EventSnapshot): void {
+    // Type assertion for aggregate that has restoreFromSnapshot
+    const restorable = aggregate as AggregateRoot & {
+      restoreFromSnapshot?(state: unknown): void;
+    };
+
+    if (typeof restorable.restoreFromSnapshot === 'function') {
+      restorable.restoreFromSnapshot(snapshot.state);
+    }
+
+    // Update version
+    (aggregate as any).version = snapshot.version;
+  }
+
+  /**
+   * Create snapshot for aggregate
+   */
+  private async createSnapshot(aggregate: AggregateRoot): Promise<void> {
+    const snapshot: EventSnapshot = {
+      aggregateId: aggregate.id,
+      aggregateType: this.getAggregateType(aggregate),
+      version: aggregate.version,
+      state: aggregate.getState(),
+      timestamp: Date.now(),
+    };
+
+    await this.eventStore.saveSnapshot(snapshot);
+  }
+
+  /**
+   * Get aggregate type from instance
+   */
+  private getAggregateType(aggregate: AggregateRoot): 'agent' | 'task' | 'memory' | 'swarm' {
+    const typeName = aggregate.constructor.name.toLowerCase().replace('aggregate', '');
+    // Map to valid aggregate types
+    if (typeName === 'agent' || typeName === 'task' || typeName === 'memory' || typeName === 'swarm') {
+      return typeName;
+    }
+    return 'agent'; // Default fallback
+  }
+}
+
+/**
+ * Agent Aggregate - Example implementation
+ */
+export class AgentAggregate implements AggregateRoot {
+  id: string;
+  version = 0;
+
+  private state = {
+    name: '',
+    role: '',
+    status: 'idle' as string,
+    currentTask: null as string | null,
+    completedTasks: [] as string[],
+    capabilities: [] as string[],
+    createdAt: null as Date | null,
+    lastActiveAt: null as Date | null,
+  };
+
+  constructor(id: string) {
+    this.id = id;
+  }
+
+  apply(event: DomainEvent): void {
+    this.version = event.version;
+
+    switch (event.type) {
+      case 'agent:spawned':
+        this.state.name = event.payload.name as string;
+        this.state.role = event.payload.role as string;
+        this.state.capabilities = (event.payload.capabilities as string[]) ?? [];
+        this.state.status = 'idle';
+        this.state.createdAt = new Date(event.timestamp);
+        break;
+
+      case 'agent:started':
+        this.state.status = 'active';
+        this.state.lastActiveAt = new Date(event.timestamp);
+        break;
+
+      case 'agent:task-assigned':
+        this.state.currentTask = event.payload.taskId as string;
+        this.state.status = 'busy';
+        this.state.lastActiveAt = new Date(event.timestamp);
+        break;
+
+      case 'agent:task-completed':
+        this.state.completedTasks.push(event.payload.taskId as string);
+        this.state.currentTask = null;
+        this.state.status = 'active';
+        this.state.lastActiveAt = new Date(event.timestamp);
+        break;
+
+      case 'agent:terminated':
+        this.state.status = 'terminated';
+        break;
+    }
+  }
+
+  getState(): Record<string, unknown> {
+    return { ...this.state };
+  }
+
+  restoreFromSnapshot(snapshotState: unknown): void {
+    const state = snapshotState as typeof this.state;
+    this.state = {
+      ...state,
+      createdAt: state.createdAt ? new Date(state.createdAt) : null,
+      lastActiveAt: state.lastActiveAt ? new Date(state.lastActiveAt) : null,
+    };
+  }
+
+  // Getters for type safety
+  get name(): string { return this.state.name; }
+  get role(): string { return this.state.role; }
+  get status(): string { return this.state.status; }
+  get currentTask(): string | null { return this.state.currentTask; }
+  get completedTasks(): string[] { return [...this.state.completedTasks]; }
+  get capabilities(): string[] { return [...this.state.capabilities]; }
+}
+
+/**
+ * Task Aggregate - Example implementation
+ */
+export class TaskAggregate implements AggregateRoot {
+  id: string;
+  version = 0;
+
+  private state = {
+    title: '',
+    description: '',
+    type: '',
+    priority: 'normal' as string,
+    status: 'pending' as string,
+    assignedAgent: null as string | null,
+    result: null as unknown,
+    createdAt: null as Date | null,
+    startedAt: null as Date | null,
+    completedAt: null as Date | null,
+  };
+
+  constructor(id: string) {
+    this.id = id;
+  }
+
+  apply(event: DomainEvent): void {
+    this.version = event.version;
+
+    switch (event.type) {
+      case 'task:created':
+        this.state.title = event.payload.title as string;
+        this.state.description = event.payload.description as string;
+        this.state.type = event.payload.taskType as string;
+        this.state.priority = (event.payload.priority as string) ?? 'normal';
+        this.state.status = 'pending';
+        this.state.createdAt = new Date(event.timestamp);
+        break;
+
+      case 'task:started':
+        this.state.assignedAgent = event.payload.agentId as string;
+        this.state.status = 'running';
+        this.state.startedAt = new Date(event.timestamp);
+        break;
+
+      case 'task:completed':
+        this.state.result = event.payload.result;
+        this.state.status = 'completed';
+        this.state.completedAt = new Date(event.timestamp);
+        break;
+
+      case 'task:failed':
+        this.state.status = 'failed';
+        this.state.completedAt = new Date(event.timestamp);
+        break;
+
+      case 'task:cancelled':
+        this.state.status = 'cancelled';
+        this.state.completedAt = new Date(event.timestamp);
+        break;
+    }
+  }
+
+  getState(): Record<string, unknown> {
+    return { ...this.state };
+  }
+
+  restoreFromSnapshot(snapshotState: unknown): void {
+    const state = snapshotState as typeof this.state;
+    this.state = {
+      ...state,
+      createdAt: state.createdAt ? new Date(state.createdAt) : null,
+      startedAt: state.startedAt ? new Date(state.startedAt) : null,
+      completedAt: state.completedAt ? new Date(state.completedAt) : null,
+    };
+  }
+
+  // Getters
+  get title(): string { return this.state.title; }
+  get status(): string { return this.state.status; }
+  get assignedAgent(): string | null { return this.state.assignedAgent; }
+  get result(): unknown { return this.state.result; }
+}
+
+/**
+ * Factory function
+ */
+export function createStateReconstructor(
+  eventStore: EventStore,
+  options?: Partial<ReconstructorOptions>
+): StateReconstructor {
+  return new StateReconstructor(eventStore, options);
+}

package/src/events.ts

@@ -0,0 +1,367 @@
+/**
+ * V3 Event Bus System
+ * Event-driven communication for the 15-agent swarm
+ *
+ * Based on ADR-007 (Event Sourcing for State Changes)
+ */
+
+import {
+  EventType,
+  EventHandler,
+  SwarmEvent,
+  AgentId
+} from './types.js';
+
+// =============================================================================
+// Event Bus Interface
+// =============================================================================
+
+export interface IEventBus {
+  subscribe<T>(eventType: EventType, handler: EventHandler<T>): () => void;
+  subscribeAll(handler: EventHandler): () => void;
+  emit<T>(event: SwarmEvent<T>): Promise<void>;
+  emitSync<T>(event: SwarmEvent<T>): void;
+  getHistory(filter?: EventFilter): SwarmEvent[];
+  clear(): void;
+}
+
+export interface EventFilter {
+  types?: EventType[];
+  sources?: (AgentId | 'swarm')[];
+  since?: number;
+  until?: number;
+  limit?: number;
+}
+
+// =============================================================================
+// Event Store Interface (Event Sourcing)
+// =============================================================================
+
+export interface IEventStore {
+  append(event: SwarmEvent): Promise<void>;
+  getEvents(aggregateId: string, fromVersion?: number): Promise<SwarmEvent[]>;
+  getAllEvents(filter?: EventFilter): Promise<SwarmEvent[]>;
+  getSnapshot(aggregateId: string): Promise<EventStoreSnapshot | null>;
+  saveSnapshot(snapshot: EventStoreSnapshot): Promise<void>;
+}
+
+export interface EventStoreSnapshot {
+  aggregateId: string;
+  version: number;
+  state: unknown;
+  timestamp: number;
+}
+
+// =============================================================================
+// Event Bus Implementation
+// =============================================================================
+
+export class EventBus implements IEventBus {
+  private handlers: Map<EventType | '*', Set<EventHandler>> = new Map();
+  private history: SwarmEvent[] = [];
+  private maxHistorySize: number;
+
+  constructor(options: { maxHistorySize?: number } = {}) {
+    this.maxHistorySize = options.maxHistorySize ?? 10000;
+  }
+
+  subscribe<T>(eventType: EventType, handler: EventHandler<T>): () => void {
+    if (!this.handlers.has(eventType)) {
+      this.handlers.set(eventType, new Set());
+    }
+
+    const handlers = this.handlers.get(eventType)!;
+    handlers.add(handler as EventHandler);
+
+    return () => {
+      handlers.delete(handler as EventHandler);
+    };
+  }
+
+  subscribeAll(handler: EventHandler): () => void {
+    if (!this.handlers.has('*')) {
+      this.handlers.set('*', new Set());
+    }
+
+    const handlers = this.handlers.get('*')!;
+    handlers.add(handler);
+
+    return () => {
+      handlers.delete(handler);
+    };
+  }
+
+  async emit<T>(event: SwarmEvent<T>): Promise<void> {
+    this.addToHistory(event);
+
+    const typeHandlers = this.handlers.get(event.type) ?? new Set();
+    const allHandlers = this.handlers.get('*') ?? new Set();
+
+    const allPromises: Promise<void>[] = [];
+
+    for (const handler of typeHandlers) {
+      allPromises.push(this.safeExecute(handler, event));
+    }
+
+    for (const handler of allHandlers) {
+      allPromises.push(this.safeExecute(handler, event));
+    }
+
+    await Promise.all(allPromises);
+  }
+
+  emitSync<T>(event: SwarmEvent<T>): void {
+    this.addToHistory(event);
+
+    const typeHandlers = this.handlers.get(event.type) ?? new Set();
+    const allHandlers = this.handlers.get('*') ?? new Set();
+
+    for (const handler of typeHandlers) {
+      try {
+        const result = handler(event);
+        if (result instanceof Promise) {
+          result.catch(err => console.error(`Event handler error: ${err}`));
+        }
+      } catch (err) {
+        console.error(`Event handler error: ${err}`);
+      }
+    }
+
+    for (const handler of allHandlers) {
+      try {
+        const result = handler(event);
+        if (result instanceof Promise) {
+          result.catch(err => console.error(`Event handler error: ${err}`));
+        }
+      } catch (err) {
+        console.error(`Event handler error: ${err}`);
+      }
+    }
+  }
+
+  getHistory(filter?: EventFilter): SwarmEvent[] {
+    let events = [...this.history];
+
+    if (filter?.types?.length) {
+      events = events.filter(e => filter.types!.includes(e.type));
+    }
+
+    if (filter?.sources?.length) {
+      events = events.filter(e => filter.sources!.includes(e.source));
+    }
+
+    if (filter?.since) {
+      events = events.filter(e => e.timestamp >= filter.since!);
+    }
+
+    if (filter?.until) {
+      events = events.filter(e => e.timestamp <= filter.until!);
+    }
+
+    if (filter?.limit) {
+      events = events.slice(-filter.limit);
+    }
+
+    return events;
+  }
+
+  clear(): void {
+    this.history = [];
+  }
+
+  private addToHistory(event: SwarmEvent): void {
+    this.history.push(event);
+
+    if (this.history.length > this.maxHistorySize) {
+      this.history = this.history.slice(-Math.floor(this.maxHistorySize / 2));
+    }
+  }
+
+  private async safeExecute(handler: EventHandler, event: SwarmEvent): Promise<void> {
+    try {
+      await handler(event);
+    } catch (err) {
+      console.error(`Event handler error for ${event.type}: ${err}`);
+    }
+  }
+}
+
+// =============================================================================
+// In-Memory Event Store
+// =============================================================================
+
+export class InMemoryEventStore implements IEventStore {
+  private events: Map<string, SwarmEvent[]> = new Map();
+  private allEvents: SwarmEvent[] = [];
+  private snapshots: Map<string, EventStoreSnapshot> = new Map();
+
+  async append(event: SwarmEvent): Promise<void> {
+    const aggregateId = this.extractAggregateId(event);
+
+    if (!this.events.has(aggregateId)) {
+      this.events.set(aggregateId, []);
+    }
+
+    this.events.get(aggregateId)!.push(event);
+    this.allEvents.push(event);
+  }
+
+  async getEvents(aggregateId: string, fromVersion?: number): Promise<SwarmEvent[]> {
+    const events = this.events.get(aggregateId) ?? [];
+
+    if (fromVersion !== undefined) {
+      return events.slice(fromVersion);
+    }
+
+    return events;
+  }
+
+  async getAllEvents(filter?: EventFilter): Promise<SwarmEvent[]> {
+    let events = [...this.allEvents];
+
+    if (filter?.types?.length) {
+      events = events.filter(e => filter.types!.includes(e.type));
+    }
+
+    if (filter?.sources?.length) {
+      events = events.filter(e => filter.sources!.includes(e.source));
+    }
+
+    if (filter?.since) {
+      events = events.filter(e => e.timestamp >= filter.since!);
+    }
+
+    if (filter?.until) {
+      events = events.filter(e => e.timestamp <= filter.until!);
+    }
+
+    if (filter?.limit) {
+      events = events.slice(-filter.limit);
+    }
+
+    return events;
+  }
+
+  async getSnapshot(aggregateId: string): Promise<EventStoreSnapshot | null> {
+    return this.snapshots.get(aggregateId) ?? null;
+  }
+
+  async saveSnapshot(snapshot: EventStoreSnapshot): Promise<void> {
+    this.snapshots.set(snapshot.aggregateId, snapshot);
+  }
+
+  private extractAggregateId(event: SwarmEvent): string {
+    if (event.source !== 'swarm') {
+      return event.source;
+    }
+
+    if (typeof event.payload === 'object' && event.payload !== null) {
+      const payload = event.payload as Record<string, unknown>;
+      if ('agentId' in payload) return payload.agentId as string;
+      if ('taskId' in payload) return payload.taskId as string;
+    }
+
+    return 'swarm';
+  }
+}
+
+// =============================================================================
+// Event Factory Functions
+// =============================================================================
+
+let eventCounter = 0;
+
+export function createEvent<T>(
+  type: EventType,
+  source: AgentId | 'swarm',
+  payload: T
+): SwarmEvent<T> {
+  return {
+    id: `evt-${Date.now()}-${++eventCounter}`,
+    type,
+    timestamp: Date.now(),
+    source,
+    payload
+  };
+}
+
+// Agent Events
+export function agentSpawnedEvent(agentId: AgentId, role: string): SwarmEvent {
+  return createEvent('agent:spawned', 'swarm', { agentId, role });
+}
+
+export function agentStatusChangedEvent(
+  agentId: AgentId,
+  previousStatus: string,
+  newStatus: string
+): SwarmEvent {
+  return createEvent('agent:status-changed', agentId, { previousStatus, newStatus });
+}
+
+export function agentTaskAssignedEvent(agentId: AgentId, taskId: string): SwarmEvent {
+  return createEvent('agent:task-assigned', 'swarm', { agentId, taskId });
+}
+
+export function agentTaskCompletedEvent(agentId: AgentId, taskId: string, result: unknown): SwarmEvent {
+  return createEvent('agent:task-completed', agentId, { taskId, result });
+}
+
+export function agentErrorEvent(agentId: AgentId, error: Error): SwarmEvent {
+  return createEvent('agent:error', agentId, {
+    message: error.message,
+    stack: error.stack
+  });
+}
+
+// Task Events
+export function taskCreatedEvent(taskId: string, type: string, title: string): SwarmEvent {
+  return createEvent('task:created', 'swarm', { taskId, type, title });
+}
+
+export function taskQueuedEvent(taskId: string, priority: string): SwarmEvent {
+  return createEvent('task:queued', 'swarm', { taskId, priority });
+}
+
+export function taskAssignedEvent(taskId: string, agentId: AgentId): SwarmEvent {
+  return createEvent('task:assigned', 'swarm', { taskId, agentId });
+}
+
+export function taskStartedEvent(taskId: string, agentId: AgentId): SwarmEvent {
+  return createEvent('task:started', agentId, { taskId });
+}
+
+export function taskCompletedEvent(taskId: string, result: unknown): SwarmEvent {
+  return createEvent('task:completed', 'swarm', { taskId, result });
+}
+
+export function taskFailedEvent(taskId: string, error: Error): SwarmEvent {
+  return createEvent('task:failed', 'swarm', {
+    taskId,
+    error: error.message,
+    stack: error.stack
+  });
+}
+
+export function taskBlockedEvent(taskId: string, blockedBy: string[]): SwarmEvent {
+  return createEvent('task:blocked', 'swarm', { taskId, blockedBy });
+}
+
+// Swarm Events
+export function swarmInitializedEvent(config: unknown): SwarmEvent {
+  return createEvent('swarm:initialized', 'swarm', { config });
+}
+
+export function swarmPhaseChangedEvent(previousPhase: string, newPhase: string): SwarmEvent {
+  return createEvent('swarm:phase-changed', 'swarm', { previousPhase, newPhase });
+}
+
+export function swarmMilestoneReachedEvent(milestoneId: string, name: string): SwarmEvent {
+  return createEvent('swarm:milestone-reached', 'swarm', { milestoneId, name });
+}
+
+export function swarmErrorEvent(error: Error): SwarmEvent {
+  return createEvent('swarm:error', 'swarm', {
+    message: error.message,
+    stack: error.stack
+  });
+}