@holoscript/framework 6.0.3

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

@@ -0,0 +1,216 @@
+/**
+ * QuorumPolicy — Production Tests
+ */
+import { describe, it, expect } from 'vitest';
+import { QuorumPolicy } from '../QuorumPolicy';
+
+function make(cfg = {}) {
+  return new QuorumPolicy(cfg);
+}
+
+describe('QuorumPolicy — defaults', () => {
+  it('constructs with no args', () => expect(() => make()).not.toThrow());
+  it('default minimumSize=2', () => expect(make().getConfig().minimumSize).toBe(2));
+  it('default optimalSize=5', () => expect(make().getConfig().optimalSize).toBe(5));
+  it('default maximumSize=50', () => expect(make().getConfig().maximumSize).toBe(50));
+  it('default quorumPercentage=0.5', () => expect(make().getConfig().quorumPercentage).toBe(0.5));
+  it('default requireQuorumForOperations=true', () =>
+    expect(make().getConfig().requireQuorumForOperations).toBe(true));
+});
+
+describe('QuorumPolicy — config validation', () => {
+  it('throws if minimumSize > optimalSize', () =>
+    expect(() => make({ minimumSize: 10, optimalSize: 5 })).toThrow());
+  it('throws if optimalSize > maximumSize', () =>
+    expect(() => make({ optimalSize: 100, maximumSize: 50 })).toThrow());
+  it('throws if quorumPercentage < 0', () =>
+    expect(() => make({ quorumPercentage: -0.1 })).toThrow());
+  it('throws if quorumPercentage > 1', () =>
+    expect(() => make({ quorumPercentage: 1.1 })).toThrow());
+  it('quorumPercentage=0 is valid', () =>
+    expect(() => make({ quorumPercentage: 0 })).not.toThrow());
+  it('quorumPercentage=1 is valid', () =>
+    expect(() => make({ quorumPercentage: 1 })).not.toThrow());
+});
+
+describe('QuorumPolicy — setMemberCount / canJoin / canLeave', () => {
+  it('canJoin=true when below maximumSize', () => {
+    const p = make({ maximumSize: 5 });
+    p.setMemberCount(4);
+    expect(p.canJoin()).toBe(true);
+  });
+  it('canJoin=false when at maximumSize', () => {
+    const p = make({ maximumSize: 5 });
+    p.setMemberCount(5);
+    expect(p.canJoin()).toBe(false);
+  });
+  it('canLeave=true when above minimumSize', () => {
+    const p = make({ minimumSize: 2 });
+    p.setMemberCount(3);
+    expect(p.canLeave()).toBe(true);
+  });
+  it('canLeave=false when at minimumSize', () => {
+    const p = make({ minimumSize: 2 });
+    p.setMemberCount(2);
+    expect(p.canLeave()).toBe(false);
+  });
+  it('setMemberCount clamps negative to 0', () => {
+    const p = make();
+    p.setMemberCount(-5);
+    expect(p.getState().currentSize).toBe(0);
+  });
+});
+
+describe('QuorumPolicy — hasQuorum', () => {
+  // Default: optimal=5, quorumPct=0.5 → required = ceil(5*0.5)=3, effective=max(2,3)=3
+  it('false when below quorum threshold', () => {
+    const p = make();
+    p.setMemberCount(2);
+    expect(p.hasQuorum()).toBe(false);
+  });
+  it('true when at quorum threshold (3)', () => {
+    const p = make();
+    p.setMemberCount(3);
+    expect(p.hasQuorum()).toBe(true);
+  });
+  it('true at and above quorum threshold', () => {
+    const p = make();
+    p.setMemberCount(10);
+    expect(p.hasQuorum()).toBe(true);
+  });
+  it('quorumPct=0 → hasQuorum when at minimumSize', () => {
+    const p = make({ quorumPercentage: 0 });
+    p.setMemberCount(2);
+    expect(p.hasQuorum()).toBe(true);
+  });
+});
+
+describe('QuorumPolicy — canOperate', () => {
+  it('requires quorum when requireQuorumForOperations=true', () => {
+    const p = make({ requireQuorumForOperations: true });
+    p.setMemberCount(1);
+    expect(p.canOperate()).toBe(false);
+  });
+  it('only needs >0 when requireQuorumForOperations=false', () => {
+    const p = make({ requireQuorumForOperations: false });
+    p.setMemberCount(1);
+    expect(p.canOperate()).toBe(true);
+  });
+  it('0 members cannot operate regardless', () => {
+    const p = make({ requireQuorumForOperations: false });
+    p.setMemberCount(0);
+    expect(p.canOperate()).toBe(false);
+  });
+});
+
+describe('QuorumPolicy — getStatus', () => {
+  const cases: [number, string][] = [
+    [0, 'below-minimum'],
+    [1, 'below-minimum'],
+    [2, 'quorum'], // at minimumSize=2, below optimalSize=5
+    [4, 'quorum'],
+    [5, 'optimal'], // at optimalSize
+    [20, 'optimal'], // above but within maximumSize
+    [51, 'above-maximum'],
+  ];
+  for (const [count, status] of cases) {
+    it(`${count} members → ${status}`, () => {
+      const p = make();
+      p.setMemberCount(count);
+      expect(p.getStatus()).toBe(status);
+    });
+  }
+});
+
+describe('QuorumPolicy — getState', () => {
+  it('returns all required fields', () => {
+    const p = make();
+    p.setMemberCount(3);
+    const s = p.getState();
+    expect(s).toHaveProperty('currentSize', 3);
+    expect(s).toHaveProperty('status');
+    expect(s).toHaveProperty('hasQuorum');
+    expect(s).toHaveProperty('canOperate');
+    expect(s).toHaveProperty('requiredForQuorum');
+    expect(s).toHaveProperty('spotsAvailable');
+  });
+  it('spotsAvailable = maximumSize - currentSize', () => {
+    const p = make({ maximumSize: 50 });
+    p.setMemberCount(30);
+    expect(p.getState().spotsAvailable).toBe(20);
+  });
+  it('requiredForQuorum=0 when already has quorum', () => {
+    const p = make();
+    p.setMemberCount(10);
+    expect(p.getState().requiredForQuorum).toBe(0);
+  });
+  it('requiredForQuorum>0 when below quorum', () => {
+    const p = make();
+    p.setMemberCount(1);
+    expect(p.getState().requiredForQuorum).toBeGreaterThan(0);
+  });
+});
+
+describe('QuorumPolicy — shouldRecruit / shouldSplit', () => {
+  it('shouldRecruit=true below optimalSize', () => {
+    const p = make();
+    p.setMemberCount(3);
+    expect(p.shouldRecruit()).toBe(true);
+  });
+  it('shouldRecruit=false at optimalSize', () => {
+    const p = make();
+    p.setMemberCount(5);
+    expect(p.shouldRecruit()).toBe(false);
+  });
+  it('shouldSplit=false below maximumSize', () => {
+    const p = make({ maximumSize: 50 });
+    p.setMemberCount(49);
+    expect(p.shouldSplit()).toBe(false);
+  });
+  it('shouldSplit=true above maximumSize', () => {
+    const p = make({ maximumSize: 50 });
+    p.setMemberCount(51);
+    expect(p.shouldSplit()).toBe(true);
+  });
+});
+
+describe('QuorumPolicy — getHealthScore', () => {
+  it('0 members → health=0', () => {
+    const p = make();
+    p.setMemberCount(0);
+    expect(p.getHealthScore()).toBe(0);
+  });
+  it('at optimal → health=1', () => {
+    const p = make();
+    p.setMemberCount(5);
+    expect(p.getHealthScore()).toBe(1);
+  });
+  it('above optimal (within max) → health=1', () => {
+    const p = make();
+    p.setMemberCount(20);
+    expect(p.getHealthScore()).toBe(1);
+  });
+  it('between min and optimal → 0.5 < health < 1', () => {
+    const p = make();
+    p.setMemberCount(3);
+    expect(p.getHealthScore()).toBeGreaterThan(0.5);
+    expect(p.getHealthScore()).toBeLessThan(1);
+  });
+  it('below minimum → health < 0.5', () => {
+    const p = make({ minimumSize: 5 });
+    p.setMemberCount(2);
+    expect(p.getHealthScore()).toBeLessThan(0.5);
+    expect(p.getHealthScore()).toBeGreaterThan(0);
+  });
+  it('above maximum → health still >= 0.5 (degraded, not critical)', () => {
+    const p = make({ maximumSize: 10 });
+    p.setMemberCount(15);
+    expect(p.getHealthScore()).toBeGreaterThanOrEqual(0.5);
+  });
+  it('getConfig returns immutable copy', () => {
+    const p = make();
+    const c = p.getConfig();
+    c.minimumSize = 99;
+    expect(p.getConfig().minimumSize).toBe(2);
+  });
+});

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

@@ -0,0 +1,177 @@
+/**
+ * QuorumPolicy Tests
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { QuorumPolicy } from '../QuorumPolicy';
+
+describe('QuorumPolicy', () => {
+  let policy: QuorumPolicy;
+
+  beforeEach(() => {
+    policy = new QuorumPolicy({
+      minimumSize: 2,
+      optimalSize: 5,
+      maximumSize: 10,
+      quorumPercentage: 0.5,
+    });
+  });
+
+  describe('constructor', () => {
+    it('should create with default config', () => {
+      const p = new QuorumPolicy();
+      expect(p.getConfig().minimumSize).toBe(2);
+    });
+
+    it('should throw for invalid config', () => {
+      expect(() => new QuorumPolicy({ minimumSize: 10, optimalSize: 5 })).toThrow();
+      expect(() => new QuorumPolicy({ optimalSize: 20, maximumSize: 10 })).toThrow();
+      expect(() => new QuorumPolicy({ quorumPercentage: 1.5 })).toThrow();
+    });
+  });
+
+  describe('canJoin', () => {
+    it('should allow joining below max', () => {
+      policy.setMemberCount(5);
+      expect(policy.canJoin()).toBe(true);
+    });
+
+    it('should disallow joining at max', () => {
+      policy.setMemberCount(10);
+      expect(policy.canJoin()).toBe(false);
+    });
+  });
+
+  describe('canLeave', () => {
+    it('should allow leaving above minimum', () => {
+      policy.setMemberCount(5);
+      expect(policy.canLeave()).toBe(true);
+    });
+
+    it('should disallow leaving at minimum', () => {
+      policy.setMemberCount(2);
+      expect(policy.canLeave()).toBe(false);
+    });
+  });
+
+  describe('hasQuorum', () => {
+    it('should not have quorum below minimum', () => {
+      policy.setMemberCount(1);
+      expect(policy.hasQuorum()).toBe(false);
+    });
+
+    it('should have quorum at minimum if meets percentage', () => {
+      // quorumPercentage 0.5 of 5 = 2.5 -> 3, but min is 2
+      // So need max(2, 3) = 3
+      policy.setMemberCount(3);
+      expect(policy.hasQuorum()).toBe(true);
+    });
+
+    it('should have quorum at optimal', () => {
+      policy.setMemberCount(5);
+      expect(policy.hasQuorum()).toBe(true);
+    });
+  });
+
+  describe('canOperate', () => {
+    it('should not operate without quorum when required', () => {
+      policy.setMemberCount(1);
+      expect(policy.canOperate()).toBe(false);
+    });
+
+    it('should operate with quorum', () => {
+      policy.setMemberCount(3);
+      expect(policy.canOperate()).toBe(true);
+    });
+
+    it('should operate without quorum when not required', () => {
+      const p = new QuorumPolicy({ requireQuorumForOperations: false });
+      p.setMemberCount(1);
+      expect(p.canOperate()).toBe(true);
+    });
+  });
+
+  describe('getStatus', () => {
+    it('should return below-minimum for too few', () => {
+      policy.setMemberCount(1);
+      expect(policy.getStatus()).toBe('below-minimum');
+    });
+
+    it('should return quorum for sufficient members', () => {
+      policy.setMemberCount(3);
+      expect(policy.getStatus()).toBe('quorum');
+    });
+
+    it('should return optimal at optimal size', () => {
+      policy.setMemberCount(5);
+      expect(policy.getStatus()).toBe('optimal');
+    });
+
+    it('should return above-maximum when exceeded', () => {
+      policy.setMemberCount(15);
+      expect(policy.getStatus()).toBe('above-maximum');
+    });
+  });
+
+  describe('getState', () => {
+    it('should return full state object', () => {
+      policy.setMemberCount(3);
+      const state = policy.getState();
+
+      expect(state.currentSize).toBe(3);
+      expect(state.status).toBe('quorum');
+      expect(state.hasQuorum).toBe(true);
+      expect(state.canOperate).toBe(true);
+      expect(state.requiredForQuorum).toBe(0);
+      expect(state.spotsAvailable).toBe(7);
+    });
+  });
+
+  describe('shouldRecruit', () => {
+    it('should recruit below optimal', () => {
+      policy.setMemberCount(3);
+      expect(policy.shouldRecruit()).toBe(true);
+    });
+
+    it('should not recruit at optimal', () => {
+      policy.setMemberCount(5);
+      expect(policy.shouldRecruit()).toBe(false);
+    });
+  });
+
+  describe('shouldSplit', () => {
+    it('should not split below maximum', () => {
+      policy.setMemberCount(8);
+      expect(policy.shouldSplit()).toBe(false);
+    });
+
+    it('should split above maximum', () => {
+      policy.setMemberCount(12);
+      expect(policy.shouldSplit()).toBe(true);
+    });
+  });
+
+  describe('getHealthScore', () => {
+    it('should return 0 for empty', () => {
+      policy.setMemberCount(0);
+      expect(policy.getHealthScore()).toBe(0);
+    });
+
+    it('should return low score below minimum', () => {
+      policy.setMemberCount(1);
+      expect(policy.getHealthScore()).toBeLessThan(0.5);
+    });
+
+    it('should return 1 at optimal', () => {
+      policy.setMemberCount(5);
+      expect(policy.getHealthScore()).toBe(1);
+    });
+
+    it('should return partial score between min and optimal', () => {
+      policy.setMemberCount(3);
+      const score = policy.getHealthScore();
+      expect(score).toBeGreaterThan(0.5);
+      expect(score).toBeLessThan(1);
+    });
+  });
+});

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

@@ -0,0 +1,186 @@
+import { describe, it, expect } from 'vitest';
+import { SwarmCoordinator, type AgentInfo, type TaskInfo } from '../SwarmCoordinator';
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function mkCoord(cfg?: ConstructorParameters<typeof SwarmCoordinator>[0]) {
+  return new SwarmCoordinator(cfg);
+}
+
+function mkAgents(n: number): AgentInfo[] {
+  return Array.from({ length: n }, (_, i) => ({
+    id: `agent-${i}`,
+    capacity: 100,
+    load: 0,
+  }));
+}
+
+function mkTasks(n: number): TaskInfo[] {
+  return Array.from({ length: n }, (_, i) => ({
+    id: `task-${i}`,
+    complexity: 10,
+    priority: i + 1,
+  }));
+}
+
+// ─── tests ───────────────────────────────────────────────────────────────────
+
+describe('SwarmCoordinator — construction', () => {
+  it('creates without config', () => {
+    expect(() => mkCoord()).not.toThrow();
+  });
+  it('creates with partial config', () => {
+    expect(() => mkCoord({ algorithm: 'pso', populationSize: 10 })).not.toThrow();
+  });
+});
+
+describe('SwarmCoordinator — getRecommendedPopulation', () => {
+  const coord = mkCoord();
+
+  it('returns at least 15 for tiny problems', () => {
+    expect(coord.getRecommendedPopulation(1)).toBeGreaterThanOrEqual(15);
+  });
+  it('returns at most 100 for huge problems', () => {
+    expect(coord.getRecommendedPopulation(1_000_000)).toBeLessThanOrEqual(100);
+  });
+  it('scales logarithmically (10 > 1)', () => {
+    expect(coord.getRecommendedPopulation(100)).toBeGreaterThanOrEqual(
+      coord.getRecommendedPopulation(10)
+    );
+  });
+  it('returns number', () => {
+    expect(typeof coord.getRecommendedPopulation(4)).toBe('number');
+  });
+  it('result is integer-like (ceil)', () => {
+    const r = coord.getRecommendedPopulation(8);
+    expect(r).toBe(Math.round(r));
+  });
+});
+
+describe('SwarmCoordinator — optimize (pso)', () => {
+  it('returns a valid result object', async () => {
+    const coord = mkCoord({ algorithm: 'pso', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(2), mkTasks(3));
+    expect(result).toHaveProperty('bestSolution');
+    expect(result).toHaveProperty('bestFitness');
+    expect(result).toHaveProperty('converged');
+    expect(result).toHaveProperty('iterations');
+  });
+  it('bestSolution has length = number of tasks', async () => {
+    const coord = mkCoord({ algorithm: 'pso', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(3), mkTasks(4));
+    expect(result.bestSolution).toHaveLength(4);
+  });
+  it('each assignment index is within agent count', async () => {
+    const agents = mkAgents(3);
+    const coord = mkCoord({ algorithm: 'pso', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(agents, mkTasks(5));
+    result.bestSolution.forEach((agentIdx: any) => {
+      expect(agentIdx).toBeGreaterThanOrEqual(0);
+      expect(agentIdx).toBeLessThan(agents.length);
+    });
+  });
+  it('iterations > 0', async () => {
+    const coord = mkCoord({ algorithm: 'pso', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(2), mkTasks(2));
+    expect(result.iterations).toBeGreaterThan(0);
+  });
+  it('improvementPercent >= 0', async () => {
+    const coord = mkCoord({ algorithm: 'pso', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(2), mkTasks(2));
+    expect(result.improvementPercent).toBeGreaterThanOrEqual(0);
+  });
+});
+
+describe('SwarmCoordinator — optimize (aco)', () => {
+  it('returns valid result with aco algorithm', async () => {
+    const coord = mkCoord({ algorithm: 'aco', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(2), mkTasks(3));
+    expect(result).toHaveProperty('bestSolution');
+  });
+  it('aco solution length = task count', async () => {
+    const coord = mkCoord({ algorithm: 'aco', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(2), mkTasks(4));
+    expect(result.bestSolution).toHaveLength(4);
+  });
+  it('aco bestFitness is a number', async () => {
+    const coord = mkCoord({ algorithm: 'aco', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(2), mkTasks(2));
+    expect(typeof result.bestFitness).toBe('number');
+  });
+});
+
+describe('SwarmCoordinator — optimize (hybrid)', () => {
+  it('returns valid result for hybrid algorithm', async () => {
+    const coord = mkCoord({ algorithm: 'hybrid', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(2), mkTasks(3));
+    expect(result).toHaveProperty('converged');
+  });
+  it('hybrid solution length = tasks', async () => {
+    const coord = mkCoord({ algorithm: 'hybrid', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(2), mkTasks(3));
+    expect(result.bestSolution).toHaveLength(3);
+  });
+});
+
+describe('SwarmCoordinator — optimize (bees)', () => {
+  it('returns valid result for bees algorithm', async () => {
+    const coord = mkCoord({ algorithm: 'bees', populationSize: 10, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(2), mkTasks(3));
+    expect(result).toHaveProperty('bestSolution');
+  });
+});
+
+describe('SwarmCoordinator — adaptiveSizing', () => {
+  it('adaptiveSizing=true respects bounds', async () => {
+    const coord = mkCoord({ adaptiveSizing: true, algorithm: 'pso', maxIterations: 5 });
+    // Should not throw regardless of problem size
+    await expect(coord.optimize(mkAgents(5), mkTasks(5))).resolves.toBeDefined();
+  });
+  it('adaptiveSizing=false uses configured populationSize', async () => {
+    const coord = mkCoord({
+      adaptiveSizing: false,
+      populationSize: 5,
+      maxIterations: 5,
+      algorithm: 'pso',
+    });
+    await expect(coord.optimize(mkAgents(2), mkTasks(2))).resolves.toBeDefined();
+  });
+});
+
+describe('SwarmCoordinator — per-call config override', () => {
+  it('optimize accepts per-call config', async () => {
+    const coord = mkCoord({ algorithm: 'pso', maxIterations: 100 });
+    // Override maxIterations to be very small — allow +1 buffer for initial eval
+    const maxIter = 2;
+    const result = await coord.optimize(mkAgents(2), mkTasks(2), { maxIterations: maxIter });
+    expect(result.iterations).toBeLessThanOrEqual(maxIter + 1);
+  });
+  it('per-call algorithm override is respected', async () => {
+    const coord = mkCoord({ algorithm: 'hybrid', maxIterations: 5 });
+    // Override to pso
+    const result = await coord.optimize(mkAgents(2), mkTasks(2), { algorithm: 'pso' });
+    expect(result).toHaveProperty('bestSolution');
+  });
+});
+
+describe('SwarmCoordinator — edge cases', () => {
+  it('single agent, single task', async () => {
+    const coord = mkCoord({ algorithm: 'pso', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(1), mkTasks(1));
+    expect(result.bestSolution).toHaveLength(1);
+    expect(result.bestSolution[0]).toBe(0); // Only one agent
+  });
+  it('many tasks, few agents', async () => {
+    const coord = mkCoord({ algorithm: 'pso', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(mkAgents(2), mkTasks(10));
+    expect(result.bestSolution).toHaveLength(10);
+  });
+  it('high-capacity agents accept all tasks', async () => {
+    const agents: AgentInfo[] = [{ id: 'big', capacity: 9999, load: 0 }];
+    const tasks = mkTasks(5);
+    const coord = mkCoord({ algorithm: 'pso', populationSize: 5, maxIterations: 5 });
+    const result = await coord.optimize(agents, tasks);
+    expect(result).toBeDefined();
+  });
+});