@holoscript/framework 6.0.3

package/src/swarm/LeaderElection.ts

@@ -0,0 +1,393 @@
+/**
+ * Leader Election System
+ *
+ * Implements Raft-inspired leader election for agent clusters.
+ * Provides fault-tolerant leader selection with automatic failover.
+ */
+
+import type { ILeaderElection } from '@holoscript/core';
+
+export interface LeaderElectionConfig {
+  electionTimeoutMin: number; // Min election timeout (ms)
+  electionTimeoutMax: number; // Max election timeout (ms)
+  heartbeatInterval: number; // Leader heartbeat interval (ms)
+  quorumSize?: number; // Override quorum calculation
+}
+
+export type ElectionRole = 'leader' | 'follower' | 'candidate';
+
+export interface ElectionState {
+  term: number;
+  votedFor: string | null;
+  role: ElectionRole;
+  leaderId: string | null;
+  votes: Set<string>;
+}
+
+const DEFAULT_CONFIG: LeaderElectionConfig = {
+  electionTimeoutMin: 150,
+  electionTimeoutMax: 300,
+  heartbeatInterval: 50,
+};
+
+/**
+ * Raft-inspired leader election for agent clusters
+ */
+export class LeaderElection implements ILeaderElection {
+  private nodeId: string;
+  private clusterMembers: string[];
+  private config: LeaderElectionConfig;
+  private state: ElectionState;
+  private electionTimer: ReturnType<typeof setTimeout> | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private callbacks: Set<(leaderId: string | null) => void> = new Set();
+  private messageHandler: ((from: string, message: ElectionMessage) => void) | null = null;
+
+  constructor(
+    nodeId: string,
+    clusterMembers: string[],
+    config: Partial<LeaderElectionConfig> = {}
+  ) {
+    this.nodeId = nodeId;
+    this.clusterMembers = clusterMembers.filter((id) => id !== nodeId);
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.state = {
+      term: 0,
+      votedFor: null,
+      role: 'follower',
+      leaderId: null,
+      votes: new Set(),
+    };
+  }
+
+  /**
+   * Start participating in leader election
+   */
+  async startElection(): Promise<string> {
+    this.becomeCandidate();
+
+    // Wait for election to complete
+    return new Promise((resolve) => {
+      const checkLeader = setInterval(() => {
+        if (this.state.leaderId !== null) {
+          clearInterval(checkLeader);
+          resolve(this.state.leaderId);
+        }
+      }, 10);
+
+      // Timeout safety
+      setTimeout(() => {
+        clearInterval(checkLeader);
+        resolve(this.state.leaderId ?? this.nodeId);
+      }, this.config.electionTimeoutMax * 3);
+    });
+  }
+
+  /**
+   * Get current leader
+   */
+  getLeader(): string | null {
+    return this.state.leaderId;
+  }
+
+  /**
+   * Get this node's current role
+   */
+  getRole(): ElectionRole {
+    return this.state.role;
+  }
+
+  /**
+   * Subscribe to leader changes
+   */
+  onLeaderChange(callback: (leaderId: string | null) => void): () => void {
+    this.callbacks.add(callback);
+    return () => this.callbacks.delete(callback);
+  }
+
+  /**
+   * Handle incoming election message
+   */
+  handleMessage(from: string, message: ElectionMessage): void {
+    switch (message.type) {
+      case 'request-vote':
+        this.handleVoteRequest(from, message);
+        break;
+      case 'vote-response':
+        this.handleVoteResponse(from, message);
+        break;
+      case 'heartbeat':
+        this.handleHeartbeat(from, message);
+        break;
+    }
+  }
+
+  /**
+   * Set message handler for sending messages to other nodes
+   */
+  setMessageHandler(handler: (from: string, message: ElectionMessage) => void): void {
+    this.messageHandler = handler;
+  }
+
+  /**
+   * Simulate receiving vote from another node (for testing/local clusters)
+   */
+  receiveVote(voterId: string): void {
+    if (this.state.role === 'candidate') {
+      this.state.votes.add(voterId);
+      this.checkElectionWin();
+    }
+  }
+
+  /**
+   * Stop participating in election
+   */
+  stop(): void {
+    if (this.electionTimer) {
+      clearTimeout(this.electionTimer);
+      this.electionTimer = null;
+    }
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  /**
+   * Transition to candidate role and start election
+   */
+  private becomeCandidate(): void {
+    this.state.term++;
+    this.state.role = 'candidate';
+    this.state.votedFor = this.nodeId;
+    this.state.votes = new Set([this.nodeId]); // Vote for self
+
+    this.resetElectionTimer();
+    this.requestVotes();
+    this.checkElectionWin();
+  }
+
+  /**
+   * Transition to leader role
+   */
+  private becomeLeader(): void {
+    this.state.role = 'leader';
+    this.state.leaderId = this.nodeId;
+
+    if (this.electionTimer) {
+      clearTimeout(this.electionTimer);
+      this.electionTimer = null;
+    }
+
+    // Start sending heartbeats
+    this.heartbeatTimer = setInterval(() => {
+      this.sendHeartbeats();
+    }, this.config.heartbeatInterval);
+
+    this.notifyLeaderChange();
+  }
+
+  /**
+   * Transition to follower role
+   */
+  private becomeFollower(leaderId: string, term: number): void {
+    const wasLeader = this.state.role === 'leader';
+
+    this.state.role = 'follower';
+    this.state.leaderId = leaderId;
+    this.state.term = term;
+    this.state.votedFor = null;
+    this.state.votes.clear();
+
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+
+    this.resetElectionTimer();
+
+    if (wasLeader || this.state.leaderId !== leaderId) {
+      this.notifyLeaderChange();
+    }
+  }
+
+  /**
+   * Request votes from all cluster members
+   */
+  private requestVotes(): void {
+    const message: VoteRequestMessage = {
+      type: 'request-vote',
+      term: this.state.term,
+      candidateId: this.nodeId,
+    };
+
+    // In a real implementation, this would send over network
+    // For now, simulate immediate responses from local cluster
+    if (this.messageHandler) {
+      for (const member of this.clusterMembers) {
+        this.messageHandler(member, message);
+      }
+    } else {
+      // Simulate local cluster - all nodes vote for first candidate
+      for (const member of this.clusterMembers) {
+        this.receiveVote(member);
+      }
+    }
+  }
+
+  /**
+   * Check if we've won the election
+   */
+  private checkElectionWin(): void {
+    const quorum = this.getQuorumSize();
+
+    if (this.state.votes.size >= quorum && this.state.role === 'candidate') {
+      this.becomeLeader();
+    }
+  }
+
+  /**
+   * Send heartbeats to all followers
+   */
+  private sendHeartbeats(): void {
+    if (this.state.role !== 'leader') return;
+
+    const message: HeartbeatMessage = {
+      type: 'heartbeat',
+      term: this.state.term,
+      leaderId: this.nodeId,
+    };
+
+    if (this.messageHandler) {
+      for (const member of this.clusterMembers) {
+        this.messageHandler(member, message);
+      }
+    }
+  }
+
+  /**
+   * Handle vote request from candidate
+   */
+  private handleVoteRequest(from: string, message: VoteRequestMessage): void {
+    // If we've already voted in this term or candidate's term is old, reject
+    if (message.term < this.state.term) {
+      return;
+    }
+
+    // If candidate's term is newer, update our term
+    if (message.term > this.state.term) {
+      this.state.term = message.term;
+      this.state.votedFor = null;
+    }
+
+    // Grant vote if we haven't voted in this term
+    if (this.state.votedFor === null || this.state.votedFor === message.candidateId) {
+      this.state.votedFor = message.candidateId;
+
+      const response: VoteResponseMessage = {
+        type: 'vote-response',
+        term: this.state.term,
+        voteGranted: true,
+      };
+
+      if (this.messageHandler) {
+        this.messageHandler(from, response);
+      }
+    }
+  }
+
+  /**
+   * Handle vote response
+   */
+  private handleVoteResponse(from: string, message: VoteResponseMessage): void {
+    if (message.term > this.state.term) {
+      this.becomeFollower(from, message.term);
+      return;
+    }
+
+    if (this.state.role === 'candidate' && message.voteGranted) {
+      this.state.votes.add(from);
+      this.checkElectionWin();
+    }
+  }
+
+  /**
+   * Handle heartbeat from leader
+   */
+  private handleHeartbeat(from: string, message: HeartbeatMessage): void {
+    if (message.term >= this.state.term) {
+      this.becomeFollower(message.leaderId, message.term);
+      this.resetElectionTimer();
+    }
+  }
+
+  /**
+   * Reset election timeout
+   */
+  private resetElectionTimer(): void {
+    if (this.electionTimer) {
+      clearTimeout(this.electionTimer);
+    }
+
+    const timeout = this.getRandomElectionTimeout();
+
+    this.electionTimer = setTimeout(() => {
+      if (this.state.role !== 'leader') {
+        this.becomeCandidate();
+      }
+    }, timeout);
+  }
+
+  /**
+   * Get random election timeout in configured range
+   */
+  private getRandomElectionTimeout(): number {
+    const { electionTimeoutMin, electionTimeoutMax } = this.config;
+    return electionTimeoutMin + Math.random() * (electionTimeoutMax - electionTimeoutMin);
+  }
+
+  /**
+   * Calculate quorum size (majority)
+   */
+  private getQuorumSize(): number {
+    if (this.config.quorumSize) {
+      return this.config.quorumSize;
+    }
+    const totalNodes = this.clusterMembers.length + 1; // Include self
+    return Math.floor(totalNodes / 2) + 1;
+  }
+
+  /**
+   * Notify all callbacks of leader change
+   */
+  private notifyLeaderChange(): void {
+    for (const callback of this.callbacks) {
+      try {
+        callback(this.state.leaderId);
+      } catch (_error) {
+        // Ignore callback errors
+      }
+    }
+  }
+}
+
+// Message types
+export type ElectionMessage = VoteRequestMessage | VoteResponseMessage | HeartbeatMessage;
+
+export interface VoteRequestMessage {
+  type: 'request-vote';
+  term: number;
+  candidateId: string;
+}
+
+export interface VoteResponseMessage {
+  type: 'vote-response';
+  term: number;
+  voteGranted: boolean;
+}
+
+export interface HeartbeatMessage {
+  type: 'heartbeat';
+  term: number;
+  leaderId: string;
+}

package/src/swarm/PSOEngine.ts

@@ -0,0 +1,206 @@
+/**
+ * Particle Swarm Optimization Engine
+ *
+ * Implements PSO algorithm for agent-task assignment optimization.
+ * Each particle represents a potential solution (task-to-agent mapping).
+ */
+
+export interface PSOConfig {
+  populationSize: number;
+  maxIterations: number;
+  convergenceThreshold: number;
+  inertiaWeight: number;
+  cognitiveWeight: number;
+  socialWeight: number;
+  velocityClamp: number;
+}
+
+export interface Particle {
+  position: number[];
+  velocity: number[];
+  personalBest: number[];
+  personalBestFitness: number;
+}
+
+export interface PSOResult {
+  bestSolution: number[];
+  bestFitness: number;
+  converged: boolean;
+  iterations: number;
+  fitnessHistory: number[];
+}
+
+const DEFAULT_CONFIG: PSOConfig = {
+  populationSize: 30,
+  maxIterations: 100,
+  convergenceThreshold: 0.001,
+  inertiaWeight: 0.729,
+  cognitiveWeight: 1.49445,
+  socialWeight: 1.49445,
+  velocityClamp: 4.0,
+};
+
+/**
+ * Particle Swarm Optimization engine for task assignment
+ */
+export class PSOEngine {
+  private config: PSOConfig;
+
+  constructor(config: Partial<PSOConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Optimize task assignment using PSO
+   *
+   * @param agentCount Number of available agents
+   * @param taskCount Number of tasks to assign
+   * @param fitnessFunction Function to evaluate solution quality (higher is better)
+   * @returns Optimization result with best assignment
+   */
+  async optimize(
+    agentCount: number,
+    taskCount: number,
+    fitnessFunction: (assignment: number[]) => number
+  ): Promise<PSOResult> {
+    const { populationSize, maxIterations, convergenceThreshold } = this.config;
+
+    // Initialize swarm
+    const particles = this.initializeSwarm(populationSize, taskCount, agentCount);
+
+    // Track global best
+    let globalBest: number[] = [...particles[0].personalBest];
+    let globalBestFitness = particles[0].personalBestFitness;
+
+    // Find initial global best
+    for (const particle of particles) {
+      if (particle.personalBestFitness > globalBestFitness) {
+        globalBestFitness = particle.personalBestFitness;
+        globalBest = [...particle.personalBest];
+      }
+    }
+
+    const fitnessHistory: number[] = [globalBestFitness];
+    let converged = false;
+    let iteration = 0;
+
+    // Main optimization loop
+    for (iteration = 0; iteration < maxIterations; iteration++) {
+      const previousBest = globalBestFitness;
+
+      // Update each particle
+      for (const particle of particles) {
+        this.updateVelocity(particle, globalBest);
+        this.updatePosition(particle, agentCount);
+
+        // Evaluate new position
+        const fitness = fitnessFunction(this.discretize(particle.position, agentCount));
+
+        // Update personal best
+        if (fitness > particle.personalBestFitness) {
+          particle.personalBestFitness = fitness;
+          particle.personalBest = [...particle.position];
+
+          // Update global best
+          if (fitness > globalBestFitness) {
+            globalBestFitness = fitness;
+            globalBest = [...particle.personalBest];
+          }
+        }
+      }
+
+      fitnessHistory.push(globalBestFitness);
+
+      // Check convergence
+      const improvement = Math.abs(globalBestFitness - previousBest);
+      if (improvement < convergenceThreshold && iteration > 10) {
+        converged = true;
+        break;
+      }
+    }
+
+    return {
+      bestSolution: this.discretize(globalBest, agentCount),
+      bestFitness: globalBestFitness,
+      converged,
+      iterations: iteration + 1,
+      fitnessHistory,
+    };
+  }
+
+  /**
+   * Initialize the particle swarm with random positions
+   */
+  private initializeSwarm(
+    populationSize: number,
+    dimensions: number,
+    agentCount: number
+  ): Particle[] {
+    const particles: Particle[] = [];
+
+    for (let i = 0; i < populationSize; i++) {
+      const position = Array.from({ length: dimensions }, () => Math.random() * agentCount);
+      const velocity = Array.from({ length: dimensions }, () => (Math.random() - 0.5) * 2);
+
+      particles.push({
+        position,
+        velocity,
+        personalBest: [...position],
+        personalBestFitness: -Infinity,
+      });
+    }
+
+    return particles;
+  }
+
+  /**
+   * Update particle velocity based on PSO equations
+   */
+  private updateVelocity(particle: Particle, globalBest: number[]): void {
+    const { inertiaWeight, cognitiveWeight, socialWeight, velocityClamp } = this.config;
+
+    for (let d = 0; d < particle.position.length; d++) {
+      const r1 = Math.random();
+      const r2 = Math.random();
+
+      // PSO velocity update equation
+      const cognitive = cognitiveWeight * r1 * (particle.personalBest[d] - particle.position[d]);
+      const social = socialWeight * r2 * (globalBest[d] - particle.position[d]);
+
+      particle.velocity[d] = inertiaWeight * particle.velocity[d] + cognitive + social;
+
+      // Clamp velocity
+      particle.velocity[d] = Math.max(
+        -velocityClamp,
+        Math.min(velocityClamp, particle.velocity[d])
+      );
+    }
+  }
+
+  /**
+   * Update particle position
+   */
+  private updatePosition(particle: Particle, agentCount: number): void {
+    for (let d = 0; d < particle.position.length; d++) {
+      particle.position[d] += particle.velocity[d];
+
+      // Clamp to valid range [0, agentCount)
+      particle.position[d] = Math.max(0, Math.min(agentCount - 0.001, particle.position[d]));
+    }
+  }
+
+  /**
+   * Convert continuous positions to discrete agent indices
+   */
+  private discretize(position: number[], agentCount: number): number[] {
+    return position.map((p) => Math.floor(Math.max(0, Math.min(agentCount - 1, p))));
+  }
+
+  /**
+   * Get recommended population size for problem
+   */
+  getRecommendedPopulation(problemSize: number): number {
+    // Heuristic: 10-50 particles based on problem size
+    return Math.min(50, Math.max(10, Math.ceil(problemSize * 1.5)));
+  }
+}