@sparkleideas/shared 3.0.0-alpha.7

package/src/core/interfaces/coordinator.interface.ts

@@ -0,0 +1,363 @@
+/**
+ * V3 Coordinator Interfaces
+ * Domain-Driven Design - Coordination Bounded Context
+ * Aligned with ADR-003 (Single Coordination Engine)
+ */
+
+import type { ITask, ITaskResult } from './task.interface.js';
+import type { IAgent, IAgentConfig } from './agent.interface.js';
+
+/**
+ * Swarm topology types
+ */
+export type SwarmTopology =
+  | 'hierarchical'
+  | 'mesh'
+  | 'ring'
+  | 'star'
+  | 'adaptive'
+  | 'hierarchical-mesh';
+
+/**
+ * Coordination status
+ */
+export type CoordinationStatus =
+  | 'initializing'
+  | 'ready'
+  | 'coordinating'
+  | 'degraded'
+  | 'error'
+  | 'shutdown';
+
+/**
+ * Swarm configuration
+ */
+export interface ISwarmConfig {
+  topology: SwarmTopology;
+  maxAgents: number;
+
+  autoScale?: {
+    enabled: boolean;
+    minAgents: number;
+    maxAgents: number;
+    scaleUpThreshold: number;
+    scaleDownThreshold: number;
+  };
+
+  coordination?: {
+    consensusRequired: boolean;
+    timeoutMs: number;
+    retryPolicy: {
+      maxRetries: number;
+      backoffMs: number;
+    };
+  };
+
+  communication?: {
+    protocol: 'events' | 'messages' | 'shared-memory';
+    batchSize: number;
+    flushIntervalMs: number;
+  };
+
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Swarm state
+ */
+export interface ISwarmState {
+  readonly id: string;
+  readonly topology: SwarmTopology;
+  readonly createdAt: Date;
+
+  status: CoordinationStatus;
+  agentCount: number;
+  taskCount: number;
+
+  metrics?: {
+    throughput: number;
+    latencyMs: number;
+    successRate: number;
+    resourceUtilization: number;
+  };
+}
+
+/**
+ * Coordinator interface - unified coordination engine
+ */
+export interface ICoordinator {
+  /**
+   * Initialize the coordinator
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Shutdown the coordinator
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Initialize a swarm with configuration
+   */
+  initializeSwarm(config: ISwarmConfig): Promise<ISwarmState>;
+
+  /**
+   * Get swarm state
+   */
+  getSwarmState(): ISwarmState | undefined;
+
+  /**
+   * Assign a task to an agent
+   */
+  assignTask(task: ITask, agentId: string): Promise<void>;
+
+  /**
+   * Get tasks assigned to an agent
+   */
+  getAgentTasks(agentId: string): Promise<ITask[]>;
+
+  /**
+   * Get task count for an agent
+   */
+  getAgentTaskCount(agentId: string): Promise<number>;
+
+  /**
+   * Cancel a task
+   */
+  cancelTask(taskId: string): Promise<void>;
+
+  /**
+   * Report task completion
+   */
+  reportTaskComplete(taskId: string, result: ITaskResult): Promise<void>;
+
+  /**
+   * Get coordination health status
+   */
+  getHealthStatus(): Promise<{ healthy: boolean; error?: string; metrics?: Record<string, number> }>;
+
+  /**
+   * Perform maintenance tasks
+   */
+  performMaintenance(): Promise<void>;
+}
+
+/**
+ * Coordination manager interface - higher-level orchestration
+ */
+export interface ICoordinationManager extends ICoordinator {
+  /**
+   * Register an agent with the coordinator
+   */
+  registerAgent(agent: IAgent): Promise<void>;
+
+  /**
+   * Unregister an agent
+   */
+  unregisterAgent(agentId: string): Promise<void>;
+
+  /**
+   * Get all registered agents
+   */
+  getRegisteredAgents(): IAgent[];
+
+  /**
+   * Request agent consensus on a decision
+   */
+  requestConsensus(topic: string, options: unknown[], timeout?: number): Promise<unknown>;
+
+  /**
+   * Broadcast message to all agents
+   */
+  broadcast(message: unknown): Promise<void>;
+
+  /**
+   * Send message to specific agent
+   */
+  sendToAgent(agentId: string, message: unknown): Promise<void>;
+
+  /**
+   * Acquire a distributed lock
+   */
+  acquireLock(resourceId: string, agentId: string, timeout?: number): Promise<boolean>;
+
+  /**
+   * Release a distributed lock
+   */
+  releaseLock(resourceId: string, agentId: string): Promise<void>;
+
+  /**
+   * Check for deadlocks
+   */
+  detectDeadlocks(): Promise<{ detected: boolean; agents?: string[]; resources?: string[] }>;
+}
+
+/**
+ * Health status for components
+ */
+export interface IHealthStatus {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  components: Record<string, IComponentHealth>;
+  timestamp: Date;
+}
+
+/**
+ * Component health details
+ */
+export interface IComponentHealth {
+  name: string;
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  lastCheck: Date;
+  error?: string;
+  metrics?: Record<string, number>;
+}
+
+/**
+ * Health monitor interface
+ */
+export interface IHealthMonitor {
+  /**
+   * Start health monitoring
+   */
+  start(): void;
+
+  /**
+   * Stop health monitoring
+   */
+  stop(): void;
+
+  /**
+   * Get current health status
+   */
+  getStatus(): Promise<IHealthStatus>;
+
+  /**
+   * Register a health check
+   */
+  registerCheck(
+    name: string,
+    check: () => Promise<{ healthy: boolean; error?: string; metrics?: Record<string, number> }>
+  ): void;
+
+  /**
+   * Unregister a health check
+   */
+  unregisterCheck(name: string): void;
+
+  /**
+   * Get health history
+   */
+  getHistory(limit?: number): IHealthStatus[];
+
+  /**
+   * Subscribe to health changes
+   */
+  onHealthChange(callback: (status: IHealthStatus) => void): () => void;
+}
+
+/**
+ * Metrics collector interface
+ */
+export interface IMetricsCollector {
+  /**
+   * Start metrics collection
+   */
+  start(): void;
+
+  /**
+   * Stop metrics collection
+   */
+  stop(): void;
+
+  /**
+   * Record a metric value
+   */
+  record(name: string, value: number, tags?: Record<string, string>): void;
+
+  /**
+   * Increment a counter
+   */
+  increment(name: string, value?: number, tags?: Record<string, string>): void;
+
+  /**
+   * Record a timing
+   */
+  timing(name: string, durationMs: number, tags?: Record<string, string>): void;
+
+  /**
+   * Get current metrics
+   */
+  getMetrics(): Record<string, { value: number; count: number; avg: number; min: number; max: number }>;
+
+  /**
+   * Reset all metrics
+   */
+  reset(): void;
+}
+
+/**
+ * Orchestrator metrics structure
+ */
+export interface IOrchestratorMetrics {
+  uptime: number;
+  totalAgents: number;
+  activeAgents: number;
+  totalTasks: number;
+  completedTasks: number;
+  failedTasks: number;
+  queuedTasks: number;
+  avgTaskDuration: number;
+  memoryUsage: NodeJS.MemoryUsage;
+  cpuUsage: NodeJS.CpuUsage;
+  timestamp: Date;
+}
+
+/**
+ * Main orchestrator interface - facade for all orchestration capabilities
+ */
+export interface IOrchestrator {
+  /**
+   * Initialize the orchestrator
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Shutdown the orchestrator
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Get health status
+   */
+  getHealthStatus(): Promise<IHealthStatus>;
+
+  /**
+   * Get orchestrator metrics
+   */
+  getMetrics(): Promise<IOrchestratorMetrics>;
+
+  /**
+   * Spawn a new agent
+   */
+  spawnAgent(config: IAgentConfig): Promise<IAgent>;
+
+  /**
+   * Terminate an agent
+   */
+  terminateAgent(agentId: string, reason?: string): Promise<void>;
+
+  /**
+   * Submit a task
+   */
+  submitTask(task: ITask): Promise<ITaskResult>;
+
+  /**
+   * Get task by ID
+   */
+  getTask(taskId: string): Promise<ITask | undefined>;
+
+  /**
+   * Cancel a task
+   */
+  cancelTask(taskId: string): Promise<void>;
+}

package/src/core/interfaces/event.interface.ts

@@ -0,0 +1,267 @@
+/**
+ * V3 Event Interfaces
+ * Domain-Driven Design - Event Sourcing Pattern (ADR-007)
+ */
+
+/**
+ * Event priority levels
+ */
+export type EventPriority = 'critical' | 'high' | 'normal' | 'low';
+
+/**
+ * Core event structure
+ */
+export interface IEvent<T = unknown> {
+  readonly id: string;
+  readonly type: string;
+  readonly timestamp: Date;
+  readonly source: string;
+
+  payload: T;
+  priority?: EventPriority;
+  correlationId?: string;
+  causationId?: string;
+
+  metadata?: {
+    version?: number;
+    userId?: string;
+    sessionId?: string;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Event creation parameters
+ */
+export interface IEventCreate<T = unknown> {
+  type: string;
+  payload: T;
+  source?: string;
+  priority?: EventPriority;
+  correlationId?: string;
+  causationId?: string;
+  metadata?: IEvent['metadata'];
+}
+
+/**
+ * Event handler function type
+ */
+export type IEventHandler<T = unknown> = (event: IEvent<T>) => void | Promise<void>;
+
+/**
+ * Event filter for subscriptions
+ */
+export interface IEventFilter {
+  types?: string[];
+  sources?: string[];
+  priority?: EventPriority[];
+  correlationId?: string;
+}
+
+/**
+ * Event subscription handle
+ */
+export interface IEventSubscription {
+  readonly id: string;
+  readonly filter: IEventFilter;
+
+  /**
+   * Unsubscribe from events
+   */
+  unsubscribe(): void;
+
+  /**
+   * Pause subscription
+   */
+  pause(): void;
+
+  /**
+   * Resume subscription
+   */
+  resume(): void;
+
+  /**
+   * Check if subscription is active
+   */
+  isActive(): boolean;
+}
+
+/**
+ * Event bus interface for pub/sub communication
+ */
+export interface IEventBus {
+  /**
+   * Emit an event to all subscribers
+   */
+  emit<T = unknown>(type: string, payload: T, options?: Partial<IEventCreate<T>>): void;
+
+  /**
+   * Emit an event and wait for all handlers
+   */
+  emitAsync<T = unknown>(type: string, payload: T, options?: Partial<IEventCreate<T>>): Promise<void>;
+
+  /**
+   * Subscribe to events matching a type pattern
+   */
+  on<T = unknown>(type: string, handler: IEventHandler<T>): IEventSubscription;
+
+  /**
+   * Subscribe to events with filter
+   */
+  subscribe<T = unknown>(filter: IEventFilter, handler: IEventHandler<T>): IEventSubscription;
+
+  /**
+   * Subscribe to a single event occurrence
+   */
+  once<T = unknown>(type: string, handler: IEventHandler<T>): IEventSubscription;
+
+  /**
+   * Remove a specific handler
+   */
+  off(type: string, handler: IEventHandler): void;
+
+  /**
+   * Remove all handlers for a type
+   */
+  removeAllListeners(type?: string): void;
+
+  /**
+   * Get count of listeners for a type
+   */
+  listenerCount(type: string): number;
+
+  /**
+   * Get all event types with active listeners
+   */
+  eventNames(): string[];
+}
+
+/**
+ * System event types enumeration
+ */
+export const SystemEventTypes = {
+  // System lifecycle
+  SYSTEM_READY: 'system:ready',
+  SYSTEM_SHUTDOWN: 'system:shutdown',
+  SYSTEM_ERROR: 'system:error',
+  SYSTEM_HEALTHCHECK: 'system:healthcheck',
+
+  // Agent lifecycle
+  AGENT_SPAWNED: 'agent:spawned',
+  AGENT_TERMINATED: 'agent:terminated',
+  AGENT_ERROR: 'agent:error',
+  AGENT_IDLE: 'agent:idle',
+  AGENT_BUSY: 'agent:busy',
+  AGENT_HEALTH_CHANGED: 'agent:health:changed',
+
+  // Task lifecycle
+  TASK_CREATED: 'task:created',
+  TASK_ASSIGNED: 'task:assigned',
+  TASK_STARTED: 'task:started',
+  TASK_COMPLETED: 'task:completed',
+  TASK_FAILED: 'task:failed',
+  TASK_CANCELLED: 'task:cancelled',
+  TASK_TIMEOUT: 'task:timeout',
+  TASK_RETRY: 'task:retry',
+
+  // Session lifecycle
+  SESSION_CREATED: 'session:created',
+  SESSION_RESTORED: 'session:restored',
+  SESSION_TERMINATED: 'session:terminated',
+  SESSION_PERSISTED: 'session:persisted',
+
+  // Memory events
+  MEMORY_STORED: 'memory:stored',
+  MEMORY_RETRIEVED: 'memory:retrieved',
+  MEMORY_CLEARED: 'memory:cleared',
+
+  // Coordination events
+  COORDINATION_STARTED: 'coordination:started',
+  COORDINATION_COMPLETED: 'coordination:completed',
+  DEADLOCK_DETECTED: 'coordination:deadlock',
+
+  // Metrics events
+  METRICS_COLLECTED: 'metrics:collected',
+} as const;
+
+export type SystemEventType = typeof SystemEventTypes[keyof typeof SystemEventTypes];
+
+/**
+ * Event store interface for event sourcing
+ */
+export interface IEventStore {
+  /**
+   * Append an event to the store
+   */
+  append(event: IEvent): Promise<void>;
+
+  /**
+   * Get events by aggregate ID
+   */
+  getByAggregateId(aggregateId: string, fromVersion?: number): Promise<IEvent[]>;
+
+  /**
+   * Get events by type
+   */
+  getByType(type: string, options?: { limit?: number; offset?: number }): Promise<IEvent[]>;
+
+  /**
+   * Get events in time range
+   */
+  getByTimeRange(start: Date, end: Date): Promise<IEvent[]>;
+
+  /**
+   * Get events by correlation ID
+   */
+  getByCorrelationId(correlationId: string): Promise<IEvent[]>;
+
+  /**
+   * Get all events (paginated)
+   */
+  getAll(options?: { limit?: number; offset?: number }): Promise<IEvent[]>;
+
+  /**
+   * Get event count
+   */
+  count(filter?: IEventFilter): Promise<number>;
+
+  /**
+   * Clear old events
+   */
+  prune(olderThan: Date): Promise<number>;
+}
+
+/**
+ * Event coordinator for routing and orchestration
+ */
+export interface IEventCoordinator {
+  /**
+   * Initialize the coordinator
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Shutdown the coordinator
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Route an event to appropriate handlers
+   */
+  route(event: IEvent): Promise<void>;
+
+  /**
+   * Register a handler for event routing
+   */
+  registerHandler(type: string, handler: IEventHandler): void;
+
+  /**
+   * Unregister a handler
+   */
+  unregisterHandler(type: string, handler: IEventHandler): void;
+
+  /**
+   * Get event bus instance
+   */
+  getEventBus(): IEventBus;
+}

package/src/core/interfaces/index.ts

@@ -0,0 +1,19 @@
+/**
+ * V3 Core Interfaces - Public API
+ * Domain-Driven Design with Clean Architecture
+ */
+
+// Task interfaces
+export * from './task.interface.js';
+
+// Agent interfaces
+export * from './agent.interface.js';
+
+// Event interfaces
+export * from './event.interface.js';
+
+// Memory interfaces
+export * from './memory.interface.js';
+
+// Coordinator interfaces
+export * from './coordinator.interface.js';