@holoscript/framework 6.0.3

package/src/swarm/__tests__/LeaderElection.prod.test.ts

@@ -0,0 +1,196 @@
+/**
+ * LeaderElection.prod.test.ts
+ *
+ * Production tests for Raft-inspired LeaderElection:
+ * immediate single-node election, receiveVote quorum mechanics,
+ * onLeaderChange callbacks, handleMessage routing, and stop() cleanup.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { LeaderElection } from '../LeaderElection';
+
+describe('LeaderElection', () => {
+  let le: LeaderElection;
+
+  afterEach(() => {
+    le?.stop();
+  });
+
+  // -------------------------------------------------------------------------
+  // Single-node election
+  // -------------------------------------------------------------------------
+  describe('single-node cluster', () => {
+    it('node elects itself immediately (no other members)', async () => {
+      le = new LeaderElection('node-1', []);
+      const leader = await le.startElection();
+      expect(leader).toBe('node-1');
+      le.stop();
+    });
+
+    it('becomes leader after startElection', async () => {
+      le = new LeaderElection('node-1', []);
+      await le.startElection();
+      expect(le.getRole()).toBe('leader');
+      le.stop();
+    });
+
+    it('getLeader returns self after winning', async () => {
+      le = new LeaderElection('node-1', []);
+      await le.startElection();
+      expect(le.getLeader()).toBe('node-1');
+      le.stop();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // receiveVote — quorum mechanics
+  // -------------------------------------------------------------------------
+  describe('receiveVote() — quorum', () => {
+    it('3-node cluster: receiving both other votes makes this node leader', async () => {
+      le = new LeaderElection('node-1', ['node-2', 'node-3'], {
+        electionTimeoutMin: 9000,
+        electionTimeoutMax: 10000, // prevent auto-trigger
+      });
+      // Manually trigger candidate state
+      const electionPromise = le.startElection(); // triggers becomeCandidate
+      // Give it a tick to set candidate state
+      await new Promise((r) => setTimeout(r, 20));
+      le.receiveVote('node-2');
+      le.receiveVote('node-3');
+      const leader = await electionPromise;
+      expect(leader).toBe('node-1');
+      le.stop();
+    });
+
+    it('insufficient votes keeps node as candidate', async () => {
+      le = new LeaderElection('node-1', ['node-2', 'node-3', 'node-4'], {
+        electionTimeoutMin: 9000,
+        electionTimeoutMax: 10000,
+        quorumSize: 4, // need 4 votes to win
+      });
+      // Block local simulation by providing a no-op messageHandler
+      le.setMessageHandler(() => {}); // messages go nowhere → no auto-votes
+      le.startElection(); // triggers becomeCandidate (starts election timer, sends vote requests to handler)
+      await new Promise((r) => setTimeout(r, 20));
+      // Self vote is counted, only 1 more vote → still needs 2 more for quorum=4
+      le.receiveVote('node-2'); // only 2 votes total (self + node-2) < quorum of 4
+      expect(le.getRole()).toBe('candidate');
+      le.stop();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // onLeaderChange callback
+  // -------------------------------------------------------------------------
+  describe('onLeaderChange()', () => {
+    it('fires callback when leader is elected', async () => {
+      le = new LeaderElection('node-1', []);
+      const callback = vi.fn();
+      le.onLeaderChange(callback);
+      await le.startElection();
+      expect(callback).toHaveBeenCalledWith('node-1');
+      le.stop();
+    });
+
+    it('unsubscribe removes callback', async () => {
+      le = new LeaderElection('node-1', []);
+      const callback = vi.fn();
+      const unsub = le.onLeaderChange(callback);
+      unsub();
+      await le.startElection();
+      expect(callback).not.toHaveBeenCalled();
+      le.stop();
+    });
+
+    it('multiple callbacks all fire', async () => {
+      le = new LeaderElection('node-1', []);
+      const cb1 = vi.fn();
+      const cb2 = vi.fn();
+      le.onLeaderChange(cb1);
+      le.onLeaderChange(cb2);
+      await le.startElection();
+      expect(cb1).toHaveBeenCalled();
+      expect(cb2).toHaveBeenCalled();
+      le.stop();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // handleMessage — heartbeat
+  // -------------------------------------------------------------------------
+  describe('handleMessage() — heartbeat', () => {
+    it('receiving heartbeat with higher term makes node a follower', () => {
+      le = new LeaderElection('node-2', ['node-1'], {
+        electionTimeoutMin: 9000,
+        electionTimeoutMax: 10000,
+      });
+      le.handleMessage('node-1', { type: 'heartbeat', term: 5, leaderId: 'node-1' });
+      expect(le.getRole()).toBe('follower');
+      expect(le.getLeader()).toBe('node-1');
+      le.stop();
+    });
+
+    it('receiving heartbeat updates leader id', () => {
+      le = new LeaderElection('node-2', ['node-1']);
+      le.handleMessage('node-1', { type: 'heartbeat', term: 3, leaderId: 'node-1' });
+      expect(le.getLeader()).toBe('node-1');
+      le.stop();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // handleMessage — request-vote
+  // -------------------------------------------------------------------------
+  describe('handleMessage() — request-vote', () => {
+    it('responds with grant when not yet voted in term', () => {
+      const sent: any[] = [];
+      le = new LeaderElection('node-2', ['node-1'], {
+        electionTimeoutMin: 9000,
+        electionTimeoutMax: 10000,
+      });
+      le.setMessageHandler((to, msg) => sent.push({ to, msg }));
+      // Term 1 vote request from node-1
+      le.handleMessage('node-1', { type: 'request-vote', term: 1, candidateId: 'node-1' });
+      const grant = sent.find((s) => s.msg.type === 'vote-response');
+      expect(grant).toBeDefined();
+      expect(grant.msg.voteGranted).toBe(true);
+      le.stop();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Initial state
+  // -------------------------------------------------------------------------
+  describe('initial state', () => {
+    it('starts as follower', () => {
+      le = new LeaderElection('n', ['m']);
+      expect(le.getRole()).toBe('follower');
+      le.stop();
+    });
+
+    it('starts with no leader', () => {
+      le = new LeaderElection('n', ['m']);
+      expect(le.getLeader()).toBeNull();
+      le.stop();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // stop()
+  // -------------------------------------------------------------------------
+  describe('stop()', () => {
+    it('does not throw when called before startElection', () => {
+      le = new LeaderElection('n', ['m']);
+      expect(() => le.stop()).not.toThrow();
+    });
+
+    it('can be called multiple times without error', async () => {
+      le = new LeaderElection('n', []);
+      await le.startElection();
+      expect(() => {
+        le.stop();
+        le.stop();
+      }).not.toThrow();
+    });
+  });
+});

package/src/swarm/__tests__/LeaderElection.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { LeaderElection } from '../LeaderElection';
+import type { ElectionMessage } from '../LeaderElection';
+
+describe('LeaderElection', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  function makeElection(nodeId: string, members: string[], config = {}) {
+    return new LeaderElection(nodeId, members, {
+      electionTimeoutMin: 10000,
+      electionTimeoutMax: 20000,
+      heartbeatInterval: 5000,
+      ...config,
+    });
+  }
+
+  it('initializes as follower with no leader', () => {
+    const e = makeElection('n1', ['n2', 'n3']);
+    expect(e.getRole()).toBe('follower');
+    expect(e.getLeader()).toBeNull();
+    e.stop();
+  });
+
+  it('filters self from cluster members', () => {
+    // If self is in member list, should not cause issues
+    const e = makeElection('n1', ['n1', 'n2', 'n3']);
+    e.stop();
+    expect(e.getRole()).toBe('follower');
+  });
+
+  it('wins election in local cluster (no message handler)', async () => {
+    vi.useFakeTimers();
+    const e = makeElection('n1', ['n2', 'n3']);
+    const promise = e.startElection();
+    vi.advanceTimersByTime(100);
+    const leader = await promise;
+    expect(leader).toBe('n1');
+    expect(e.getRole()).toBe('leader');
+    expect(e.getLeader()).toBe('n1');
+    e.stop();
+  });
+
+  it('accepts votes from peers', () => {
+    vi.useFakeTimers();
+    const e = makeElection('n1', ['n2', 'n3', 'n4', 'n5'], { quorumSize: 3 });
+    // Manually become a candidate
+    e.startElection();
+    // Already received own vote + all members' votes in local mode
+    expect(e.getRole()).toBe('leader');
+    e.stop();
+  });
+
+  it('receiveVote only counts when candidate', () => {
+    const e = makeElection('n1', ['n2']);
+    e.receiveVote('n2'); // Should be ignored, not a candidate
+    expect(e.getRole()).toBe('follower');
+    e.stop();
+  });
+
+  it('onLeaderChange fires on leader win', async () => {
+    vi.useFakeTimers();
+    const e = makeElection('n1', ['n2']);
+    const cb = vi.fn();
+    e.onLeaderChange(cb);
+    const promise = e.startElection();
+    vi.advanceTimersByTime(100);
+    await promise;
+    expect(cb).toHaveBeenCalledWith('n1');
+    e.stop();
+  });
+
+  it('onLeaderChange returns unsubscribe fn', () => {
+    vi.useFakeTimers();
+    const e = makeElection('n1', ['n2']);
+    const cb = vi.fn();
+    const unsub = e.onLeaderChange(cb);
+    unsub();
+    e.startElection();
+    vi.advanceTimersByTime(100);
+    expect(cb).not.toHaveBeenCalled();
+    e.stop();
+  });
+
+  it('handleMessage handles vote request (grants vote)', () => {
+    vi.useFakeTimers();
+    const e = makeElection('n2', ['n1']);
+    const sent: { to: string; msg: ElectionMessage }[] = [];
+    e.setMessageHandler((to, msg) => sent.push({ to, msg }));
+    // n1 asks n2 for a vote
+    e.handleMessage('n1', { type: 'request-vote', term: 1, candidateId: 'n1' });
+    expect(sent.length).toBeGreaterThan(0);
+    const resp = sent.find((s) => s.msg.type === 'vote-response');
+    expect(resp).toBeDefined();
+    expect((resp!.msg as any).voteGranted).toBe(true);
+    e.stop();
+  });
+
+  it('handleMessage rejects old-term vote request', () => {
+    vi.useFakeTimers();
+    const e = makeElection('n2', ['n1']);
+    // Force term to 5
+    e.handleMessage('n1', { type: 'heartbeat', term: 5, leaderId: 'n1' });
+    const sent: { to: string; msg: ElectionMessage }[] = [];
+    e.setMessageHandler((to, msg) => sent.push({ to, msg }));
+    // Request with old term
+    e.handleMessage('n1', { type: 'request-vote', term: 2, candidateId: 'n1' });
+    expect(sent.filter((s) => s.msg.type === 'vote-response')).toHaveLength(0);
+    e.stop();
+  });
+
+  it('handleMessage handles heartbeat (become follower)', () => {
+    vi.useFakeTimers();
+    const e = makeElection('n2', ['n1']);
+    e.handleMessage('n1', { type: 'heartbeat', term: 1, leaderId: 'n1' });
+    expect(e.getRole()).toBe('follower');
+    expect(e.getLeader()).toBe('n1');
+    e.stop();
+  });
+
+  it('handleMessage handles vote response with higher term (step down)', () => {
+    vi.useFakeTimers();
+    const e = makeElection('n1', ['n2', 'n3', 'n4'], { quorumSize: 100 }); // huge quorum so we stay candidate
+    e.setMessageHandler(() => {}); // prevent auto-vote
+    e.startElection();
+    // Now n1 is candidate. Receive vote response with higher term
+    e.handleMessage('n2', { type: 'vote-response', term: 999, voteGranted: false });
+    expect(e.getRole()).toBe('follower');
+    e.stop();
+  });
+
+  it('single-node cluster wins immediately', async () => {
+    vi.useFakeTimers();
+    const e = makeElection('solo', []);
+    const promise = e.startElection();
+    vi.advanceTimersByTime(100);
+    const leader = await promise;
+    expect(leader).toBe('solo');
+    e.stop();
+  });
+
+  it('stop clears all timers', () => {
+    vi.useFakeTimers();
+    const e = makeElection('n1', ['n2']);
+    e.startElection();
+    e.stop();
+    // Should not throw or cause issues after stop
+    expect(e.getLeader()).toBeTruthy(); // Was already elected
+  });
+});

package/src/swarm/__tests__/PSOEngine.prod.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest';
+import { PSOEngine, type PSOConfig } from '../PSOEngine';
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function mkPSO(cfg?: Partial<PSOConfig>) {
+  return new PSOEngine(cfg);
+}
+
+/** Perfect fitness fn — rewards assignment[i] === targetAgentIdx */
+function targetFitness(target: number[], agentCount: number) {
+  return (assignment: number[]) => {
+    let score = 0;
+    for (let i = 0; i < assignment.length; i++) {
+      if (assignment[i] === target[i]) score += 10;
+    }
+    return score;
+  };
+}
+
+/** Constant fitness fn — always returns same value */
+const constantFitness = (v: number) => (_: number[]) => v;
+
+// ─── tests ───────────────────────────────────────────────────────────────────
+
+describe('PSOEngine — construction / defaultConfig', () => {
+  it('creates with empty config', () => expect(() => mkPSO()).not.toThrow());
+  it('default inertiaWeight = 0.729', () => {
+    // Run a tiny optimization and check it doesn't blow up
+    expect(mkPSO()).toBeDefined();
+  });
+  it('custom config is respected', () => {
+    const pso = mkPSO({ populationSize: 5, maxIterations: 2 });
+    expect(pso).toBeDefined();
+  });
+});
+
+describe('PSOEngine — getRecommendedPopulation', () => {
+  const pso = mkPSO();
+  it('returns min 10 for tiny problems', () => {
+    expect(pso.getRecommendedPopulation(1)).toBeGreaterThanOrEqual(10);
+  });
+  it('returns max 50 for large problems', () => {
+    expect(pso.getRecommendedPopulation(1000)).toBeLessThanOrEqual(50);
+  });
+  it('scales with problem size (5 > 1)', () => {
+    expect(pso.getRecommendedPopulation(5)).toBeGreaterThanOrEqual(pso.getRecommendedPopulation(1));
+  });
+  it('returns integer', () => {
+    const r = pso.getRecommendedPopulation(6);
+    expect(r).toBe(Math.round(r));
+  });
+});
+
+describe('PSOEngine — optimize result shape', () => {
+  it('returns all required fields', async () => {
+    const pso = mkPSO({ populationSize: 5, maxIterations: 3 });
+    const result = await pso.optimize(2, 3, constantFitness(1));
+    expect(result).toHaveProperty('bestSolution');
+    expect(result).toHaveProperty('bestFitness');
+    expect(result).toHaveProperty('converged');
+    expect(result).toHaveProperty('iterations');
+    expect(result).toHaveProperty('fitnessHistory');
+  });
+  it('bestSolution has length = taskCount', async () => {
+    const pso = mkPSO({ populationSize: 5, maxIterations: 3 });
+    const result = await pso.optimize(3, 5, constantFitness(0));
+    expect(result.bestSolution).toHaveLength(5);
+  });
+  it('each solution element is a valid agent index', async () => {
+    const agentCount = 4;
+    const pso = mkPSO({ populationSize: 5, maxIterations: 3 });
+    const result = await pso.optimize(agentCount, 6, constantFitness(0));
+    result.bestSolution.forEach((idx) => {
+      expect(idx).toBeGreaterThanOrEqual(0);
+      expect(idx).toBeLessThan(agentCount);
+    });
+  });
+  it('iterations > 0', async () => {
+    const pso = mkPSO({ populationSize: 5, maxIterations: 5 });
+    const result = await pso.optimize(2, 2, constantFitness(1));
+    expect(result.iterations).toBeGreaterThan(0);
+  });
+  it('fitnessHistory is non-empty array', async () => {
+    const pso = mkPSO({ populationSize: 5, maxIterations: 3 });
+    const result = await pso.optimize(2, 2, constantFitness(5));
+    expect(Array.isArray(result.fitnessHistory)).toBe(true);
+    expect(result.fitnessHistory.length).toBeGreaterThan(0);
+  });
+  it('bestFitness matches last fitnessHistory value (non-decreasing)', async () => {
+    const pso = mkPSO({ populationSize: 10, maxIterations: 5 });
+    const result = await pso.optimize(2, 3, constantFitness(7));
+    const maxHistory = Math.max(...result.fitnessHistory);
+    expect(result.bestFitness).toBeCloseTo(maxHistory, 9);
+  });
+  it('converged = boolean', async () => {
+    const pso = mkPSO({ populationSize: 5, maxIterations: 3 });
+    const result = await pso.optimize(2, 2, constantFitness(0));
+    expect(typeof result.converged).toBe('boolean');
+  });
+});
+
+describe('PSOEngine — convergence behavior', () => {
+  it('converges when fitness is constant (no improvement)', async () => {
+    // constant fitness with zero improvement should trigger convergence after >10 iterations
+    const pso = mkPSO({ populationSize: 5, maxIterations: 50, convergenceThreshold: 0.001 });
+    const result = await pso.optimize(2, 2, constantFitness(42));
+    expect(result.converged).toBe(true);
+  });
+  it('does NOT converge when maxIterations = 5 (fewer than 10 required to check)', async () => {
+    const pso = mkPSO({ populationSize: 5, maxIterations: 5 });
+    const result = await pso.optimize(2, 2, constantFitness(1));
+    // With only 5 iterations, convergence cannot be detected (needs >10)
+    expect(result.converged).toBe(false);
+    expect(result.iterations).toBeLessThanOrEqual(6); // 5 + buffer
+  });
+});
+
+describe('PSOEngine — fitness optimization', () => {
+  it('finds high-fitness solution with obvious landscape', async () => {
+    const agentCount = 2;
+    const taskCount = 2;
+    // Fitness = sum of (agentIndex) — higher agent index is better
+    // PSO should prefer index 1 over 0
+    const pso = mkPSO({ populationSize: 20, maxIterations: 50 });
+    const result = await pso.optimize(agentCount, taskCount, (assignment) =>
+      assignment.reduce((acc, a) => acc + a, 0)
+    );
+    // All tasks should be assigned to agent 1
+    expect(result.bestFitness).toBeGreaterThan(0);
+  });
+  it('single agent — all tasks must go to agent 0', async () => {
+    const pso = mkPSO({ populationSize: 5, maxIterations: 5 });
+    const result = await pso.optimize(1, 3, constantFitness(1));
+    result.bestSolution.forEach((idx) => expect(idx).toBe(0));
+  });
+  it('fitness of bestSolution equals bestFitness', async () => {
+    const fitnessMap: Record<string, number> = {};
+    const fn = (a: number[]) => {
+      const k = a.join('-');
+      if (!fitnessMap[k]) fitnessMap[k] = Math.random() * 10;
+      return fitnessMap[k];
+    };
+    const pso = mkPSO({ populationSize: 10, maxIterations: 10 });
+    const result = await pso.optimize(3, 3, fn);
+    // The reported bestFitness must be ≥ any fitness seen in history
+    result.fitnessHistory.forEach((f) => {
+      expect(result.bestFitness).toBeGreaterThanOrEqual(f - 1e-9);
+    });
+  });
+});
+
+describe('PSOEngine — velocity clamp', () => {
+  it('does not throw with velocityClamp = 0.1', async () => {
+    const pso = mkPSO({ velocityClamp: 0.1, populationSize: 5, maxIterations: 3 });
+    await expect(pso.optimize(2, 2, constantFitness(1))).resolves.toBeDefined();
+  });
+  it('does not throw with very large velocityClamp', async () => {
+    const pso = mkPSO({ velocityClamp: 100, populationSize: 5, maxIterations: 3 });
+    await expect(pso.optimize(2, 2, constantFitness(1))).resolves.toBeDefined();
+  });
+});

package/src/swarm/__tests__/PSOEngine.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PSOEngine, type PSOConfig } from '../PSOEngine';
+
+describe('PSOEngine', () => {
+  let engine: PSOEngine;
+
+  beforeEach(() => {
+    engine = new PSOEngine();
+  });
+
+  describe('constructor', () => {
+    it('should create with default config', () => {
+      expect(engine).toBeDefined();
+    });
+
+    it('should accept custom config', () => {
+      const customConfig: Partial<PSOConfig> = {
+        populationSize: 50,
+        maxIterations: 200,
+      };
+      const customEngine = new PSOEngine(customConfig);
+      expect(customEngine).toBeDefined();
+    });
+  });
+
+  describe('optimize', () => {
+    it('should find optimal assignment for simple problem', async () => {
+      // Simple fitness: prefer lower agent indices
+      const fitnessFunction = (assignment: number[]) => {
+        return assignment.reduce((sum, agent) => sum - agent, 0);
+      };
+
+      const result = await engine.optimize(3, 5, fitnessFunction);
+
+      expect(result.bestSolution).toHaveLength(5);
+      expect(result.bestFitness).toBeDefined();
+      expect(result.iterations).toBeGreaterThan(0);
+      expect(result.fitnessHistory).toBeDefined();
+      expect(result.fitnessHistory.length).toBeGreaterThan(0);
+    });
+
+    it('should converge on known optimization problem', async () => {
+      // Fitness: all tasks to agent 0 is optimal
+      const fitnessFunction = (assignment: number[]) => {
+        return assignment.filter((a) => a === 0).length * 10;
+      };
+
+      const result = await engine.optimize(3, 10, fitnessFunction);
+
+      // Should find many assignments to agent 0
+      const agent0Count = result.bestSolution.filter((a) => a === 0).length;
+      expect(agent0Count).toBeGreaterThan(5);
+    });
+
+    it('should respect agent count bounds', async () => {
+      const agentCount = 5;
+      const result = await engine.optimize(agentCount, 20, () => 1);
+
+      expect(result.bestSolution.every((a) => a >= 0 && a < agentCount)).toBe(true);
+    });
+
+    it('should return discrete integer assignments', async () => {
+      const result = await engine.optimize(4, 10, () => Math.random());
+
+      expect(result.bestSolution.every((a) => Number.isInteger(a))).toBe(true);
+    });
+
+    it('should track fitness history', async () => {
+      const result = await engine.optimize(3, 5, (a) => a.length);
+
+      expect(result.fitnessHistory.length).toBeGreaterThan(1);
+      // First entry should exist
+      expect(result.fitnessHistory[0]).toBeDefined();
+    });
+
+    it('should detect convergence early', async () => {
+      // Constant fitness - should converge quickly
+      const engine = new PSOEngine({
+        maxIterations: 100,
+        convergenceThreshold: 0.01,
+      });
+
+      const result = await engine.optimize(3, 5, () => 100);
+
+      // Should converge before max iterations
+      expect(result.iterations).toBeLessThan(100);
+      expect(result.converged).toBe(true);
+    });
+  });
+
+  describe('getRecommendedPopulation', () => {
+    it('should return at least 10 for small problems', () => {
+      expect(engine.getRecommendedPopulation(1)).toBeGreaterThanOrEqual(10);
+    });
+
+    it('should cap at 50 for large problems', () => {
+      expect(engine.getRecommendedPopulation(10000)).toBeLessThanOrEqual(50);
+    });
+
+    it('should scale with problem size', () => {
+      const small = engine.getRecommendedPopulation(5);
+      const large = engine.getRecommendedPopulation(100);
+      expect(large).toBeGreaterThanOrEqual(small);
+    });
+  });
+});