@holoscript/framework 6.0.3

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

@@ -0,0 +1,373 @@
+/**
+ * SwarmManager Tests
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { SwarmManager, type SwarmEvent } from '../SwarmManager';
+
+describe('SwarmManager', () => {
+  let manager: SwarmManager;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    manager = new SwarmManager();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('createSwarm', () => {
+    it('should create a new swarm', () => {
+      const swarm = manager.createSwarm({
+        name: 'Test Swarm',
+        objective: 'Testing objectives',
+        createdBy: 'agent-1',
+      });
+
+      expect(swarm.id).toBeDefined();
+      expect(swarm.name).toBe('Test Swarm');
+      expect(swarm.objective).toBe('Testing objectives');
+      expect(swarm.createdBy).toBe('agent-1');
+      expect(swarm.status).toBe('forming');
+    });
+
+    it('should add creator as leader', () => {
+      const swarm = manager.createSwarm({
+        name: 'Test Swarm',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+
+      const leader = swarm.membership.getLeader();
+      expect(leader?.agentId).toBe('agent-1');
+    });
+
+    it('should enforce max swarms per agent', () => {
+      manager = new SwarmManager({ maxSwarmsPerAgent: 2 });
+
+      manager.createSwarm({ name: 'S1', objective: 'O1', createdBy: 'agent-1' });
+      manager.createSwarm({ name: 'S2', objective: 'O2', createdBy: 'agent-1' });
+
+      expect(() =>
+        manager.createSwarm({
+          name: 'S3',
+          objective: 'O3',
+          createdBy: 'agent-1',
+        })
+      ).toThrow('maximum swarm limit');
+    });
+
+    it('should emit swarm-created event', () => {
+      const events: SwarmEvent[] = [];
+      manager.onEvent((e) => events.push(e));
+
+      manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+
+      expect(events.some((e) => e.type === 'swarm-created')).toBe(true);
+    });
+  });
+
+  describe('joinSwarm', () => {
+    it('should add agent to swarm', () => {
+      const swarm = manager.createSwarm({
+        name: 'Test Swarm',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+
+      manager.joinSwarm(swarm.id, 'agent-2');
+
+      expect(swarm.membership.getMember('agent-2')).toBeDefined();
+    });
+
+    it('should throw for non-existent swarm', () => {
+      expect(() => manager.joinSwarm('unknown', 'agent-1')).toThrow('not found');
+    });
+
+    it('should throw for disbanded swarm', () => {
+      const swarm = manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+
+      manager.disbandSwarm(swarm.id, {
+        reason: 'Test',
+        redistributeTasks: false,
+        notifyMembers: false,
+      });
+
+      expect(() => manager.joinSwarm(swarm.id, 'agent-2')).toThrow('disbanded');
+    });
+
+    it('should allow observers to bypass swarm limit', () => {
+      manager = new SwarmManager({ maxSwarmsPerAgent: 1 });
+
+      const s1 = manager.createSwarm({ name: 'S1', objective: 'O1', createdBy: 'agent-1' });
+      const s2 = manager.createSwarm({ name: 'S2', objective: 'O2', createdBy: 'agent-2' });
+
+      // agent-1 already in 1 swarm, should still be able to observe another
+      const success = manager.joinSwarm(s2.id, 'agent-1', true);
+      expect(success).toBe(true);
+    });
+
+    it('should update status to active when quorum reached', () => {
+      manager = new SwarmManager({
+        defaultMembershipConfig: {
+          quorum: { minimumSize: 2, optimalSize: 3, maximumSize: 10 },
+        },
+      });
+
+      const swarm = manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+
+      expect(swarm.status).toBe('forming');
+
+      manager.joinSwarm(swarm.id, 'agent-2');
+      manager.joinSwarm(swarm.id, 'agent-3');
+
+      expect(swarm.status).toBe('active');
+    });
+  });
+
+  describe('leaveSwarm', () => {
+    it('should remove agent from swarm', () => {
+      const swarm = manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+      manager.joinSwarm(swarm.id, 'agent-2');
+      manager.joinSwarm(swarm.id, 'agent-3');
+
+      manager.leaveSwarm(swarm.id, 'agent-2');
+
+      expect(swarm.membership.getMember('agent-2')).toBeUndefined();
+    });
+
+    it('should update agent swarm tracking', () => {
+      const swarm = manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+      manager.joinSwarm(swarm.id, 'agent-2');
+      manager.joinSwarm(swarm.id, 'agent-3');
+
+      manager.leaveSwarm(swarm.id, 'agent-2');
+
+      const agentSwarms = manager.getAgentSwarms('agent-2');
+      expect(agentSwarms).toHaveLength(0);
+    });
+  });
+
+  describe('disbandSwarm', () => {
+    it('should mark swarm as disbanded', () => {
+      const swarm = manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+
+      manager.disbandSwarm(swarm.id, {
+        reason: 'No longer needed',
+        redistributeTasks: false,
+        notifyMembers: true,
+      });
+
+      expect(swarm.status).toBe('disbanded');
+    });
+
+    it('should remove all members', () => {
+      const swarm = manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+      manager.joinSwarm(swarm.id, 'agent-2');
+
+      manager.disbandSwarm(swarm.id, {
+        reason: 'Test',
+        redistributeTasks: false,
+        notifyMembers: false,
+      });
+
+      expect(swarm.membership.getMembers()).toHaveLength(0);
+    });
+
+    it('should emit swarm-disbanded event', () => {
+      const swarm = manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+
+      const events: SwarmEvent[] = [];
+      manager.onEvent((e) => events.push(e));
+
+      manager.disbandSwarm(swarm.id, {
+        reason: 'Test',
+        redistributeTasks: false,
+        notifyMembers: false,
+      });
+
+      expect(events.some((e) => e.type === 'swarm-disbanded')).toBe(true);
+    });
+  });
+
+  describe('getSwarm', () => {
+    it('should return swarm by id', () => {
+      const created = manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+
+      const found = manager.getSwarm(created.id);
+      expect(found?.id).toBe(created.id);
+    });
+
+    it('should return undefined for unknown id', () => {
+      const found = manager.getSwarm('unknown');
+      expect(found).toBeUndefined();
+    });
+  });
+
+  describe('getAllSwarms', () => {
+    it('should return all swarms', () => {
+      manager.createSwarm({ name: 'S1', objective: 'O1', createdBy: 'agent-1' });
+      manager.createSwarm({ name: 'S2', objective: 'O2', createdBy: 'agent-2' });
+
+      const all = manager.getAllSwarms();
+      expect(all).toHaveLength(2);
+    });
+  });
+
+  describe('getActiveSwarms', () => {
+    it('should filter out disbanded swarms', () => {
+      const s1 = manager.createSwarm({ name: 'S1', objective: 'O1', createdBy: 'agent-1' });
+      manager.createSwarm({ name: 'S2', objective: 'O2', createdBy: 'agent-2' });
+
+      manager.disbandSwarm(s1.id, {
+        reason: 'Test',
+        redistributeTasks: false,
+        notifyMembers: false,
+      });
+
+      const active = manager.getActiveSwarms();
+      expect(active).toHaveLength(1);
+    });
+  });
+
+  describe('getAgentSwarms', () => {
+    it('should return swarms agent is in', () => {
+      const s1 = manager.createSwarm({ name: 'S1', objective: 'O1', createdBy: 'agent-1' });
+      const s2 = manager.createSwarm({ name: 'S2', objective: 'O2', createdBy: 'agent-2' });
+
+      manager.joinSwarm(s2.id, 'agent-1');
+
+      const agentSwarms = manager.getAgentSwarms('agent-1');
+      expect(agentSwarms).toHaveLength(2);
+    });
+
+    it('should return empty for unknown agent', () => {
+      const swarms = manager.getAgentSwarms('unknown');
+      expect(swarms).toHaveLength(0);
+    });
+  });
+
+  describe('findSwarmsByObjective', () => {
+    it('should find swarms matching objective', () => {
+      manager.createSwarm({
+        name: 'Data Processing',
+        objective: 'Process large datasets',
+        createdBy: 'agent-1',
+      });
+      manager.createSwarm({
+        name: 'Machine Learning',
+        objective: 'Train ML models',
+        createdBy: 'agent-2',
+      });
+
+      const found = manager.findSwarmsByObjective('datasets');
+      expect(found).toHaveLength(1);
+      expect(found[0].name).toBe('Data Processing');
+    });
+
+    it('should also match by name', () => {
+      manager.createSwarm({ name: 'Data Processing', objective: 'Do stuff', createdBy: 'agent-1' });
+
+      const found = manager.findSwarmsByObjective('data');
+      expect(found).toHaveLength(1);
+    });
+  });
+
+  describe('getSwarmStats', () => {
+    it('should return swarm statistics', () => {
+      const swarm = manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+      manager.joinSwarm(swarm.id, 'agent-2');
+
+      const stats = manager.getSwarmStats(swarm.id);
+
+      expect(stats?.memberCount).toBe(2);
+      expect(stats?.ageMs).toBeGreaterThanOrEqual(0);
+      expect(stats?.healthScore).toBeGreaterThan(0);
+    });
+
+    it('should return undefined for unknown swarm', () => {
+      const stats = manager.getSwarmStats('unknown');
+      expect(stats).toBeUndefined();
+    });
+  });
+
+  describe('performMaintenance', () => {
+    it('should check for heartbeat timeouts', () => {
+      manager = new SwarmManager({
+        defaultMembershipConfig: {
+          heartbeatTimeoutMs: 1000,
+        },
+      });
+
+      const swarm = manager.createSwarm({
+        name: 'Test',
+        objective: 'Testing',
+        createdBy: 'agent-1',
+      });
+      manager.joinSwarm(swarm.id, 'agent-2');
+
+      vi.advanceTimersByTime(2000);
+
+      const affected = manager.performMaintenance();
+      expect(affected.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('event subscription', () => {
+    it('should allow subscribing to events', () => {
+      const events: SwarmEvent[] = [];
+      const unsub = manager.onEvent((e) => events.push(e));
+
+      manager.createSwarm({ name: 'Test', objective: 'Testing', createdBy: 'agent-1' });
+
+      expect(events.length).toBeGreaterThan(0);
+
+      unsub();
+      manager.createSwarm({ name: 'Test2', objective: 'Testing', createdBy: 'agent-2' });
+
+      const countAfter = events.length;
+      expect(countAfter).toBeLessThanOrEqual(events.length);
+    });
+  });
+});

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

@@ -0,0 +1,273 @@
+/**
+ * SwarmMembership — Production Tests
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SwarmMembership } from '../SwarmMembership';
+
+function make(cfg = {}) {
+  return new SwarmMembership(cfg);
+}
+
+describe('SwarmMembership — join', () => {
+  it('first join succeeds', () => {
+    const s = make();
+    expect(s.join({ agentId: 'a1' })).toBe(true);
+    expect(s.getMemberCount()).toBe(1);
+  });
+  it('first member becomes leader', () => {
+    const s = make();
+    s.join({ agentId: 'a1' });
+    expect(s.getLeader()?.agentId).toBe('a1');
+  });
+  it('second member is ordinary member', () => {
+    const s = make();
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    expect(s.getMember('a2')?.role).toBe('member');
+  });
+  it('duplicate join returns true and does not duplicate', () => {
+    const s = make();
+    s.join({ agentId: 'a1' });
+    expect(s.join({ agentId: 'a1' })).toBe(true);
+    expect(s.getMemberCount()).toBe(1);
+  });
+  it('join fails when at maximumSize', () => {
+    const s = make({ quorum: { minimumSize: 1, optimalSize: 2, maximumSize: 2 } });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    expect(s.join({ agentId: 'a3' })).toBe(false);
+    expect(s.getMemberCount()).toBe(2);
+  });
+  it('metadata is stored on member', () => {
+    const s = make();
+    s.join({ agentId: 'a1', metadata: { region: 'us-east' } });
+    expect(s.getMember('a1')?.metadata?.region).toBe('us-east');
+  });
+  it('joining with requestedRole=leader sets role after first joiner', () => {
+    const s = make();
+    s.join({ agentId: 'a1' }); // first = auto-leader
+    expect(() => s.join({ agentId: 'a2', requestedRole: 'leader' })).not.toThrow();
+  });
+});
+
+describe('SwarmMembership — leave', () => {
+  it('graceful leave succeeds for multi-member swarm', () => {
+    const s = make({ quorum: { minimumSize: 2 } });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    s.join({ agentId: 'a3' });
+    expect(s.leave({ agentId: 'a3', graceful: true })).toBe(true);
+    expect(s.getMemberCount()).toBe(2);
+  });
+  it('leave of unknown agent returns false', () => {
+    const s = make();
+    expect(s.leave({ agentId: 'nobody', graceful: true })).toBe(false);
+  });
+  it('last member forced-disbands on graceful leave', () => {
+    const s = make();
+    s.join({ agentId: 'a1' });
+    expect(s.leave({ agentId: 'a1', graceful: true })).toBe(true);
+    expect(s.getMemberCount()).toBe(0);
+  });
+  it('cannot leave when at minimumSize (quorum enforcement)', () => {
+    const s = make({ quorum: { minimumSize: 3 } });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    s.join({ agentId: 'a3' });
+    // 3 members, minimumSize=3 → canLeave=false
+    const result = s.leave({ agentId: 'a3', graceful: true });
+    // Either marks as 'leaving' (returns false) or permits for observers
+    // non-leader, ordinary member: should be blocked
+    expect(result).toBe(false);
+    expect(s.getMember('a3')?.status).toBe('leaving');
+  });
+  it('leader leave triggers re-election', () => {
+    const s = make({ quorum: { minimumSize: 1 } });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    s.leave({ agentId: 'a1', graceful: true });
+    expect(s.getLeader()?.agentId).toBe('a2');
+  });
+});
+
+describe('SwarmMembership — removeForcefully', () => {
+  it('removes member unconditionally', () => {
+    const s = make({ quorum: { minimumSize: 3 } });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    s.join({ agentId: 'a3' });
+    s.removeForcefully('a3', 'timeout');
+    expect(s.getMemberCount()).toBe(2);
+    expect(s.getMember('a3')).toBeUndefined();
+  });
+  it('force removing leader triggers re-election', () => {
+    const s = make({ quorum: { minimumSize: 1 } });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    s.removeForcefully('a1', 'kicked');
+    expect(s.getLeader()?.agentId).toBe('a2');
+  });
+  it('removing unknown agent does not throw', () => {
+    const s = make();
+    expect(() => s.removeForcefully('ghost', 'test')).not.toThrow();
+  });
+});
+
+describe('SwarmMembership — observers', () => {
+  it('observer join succeeds', () => {
+    const s = make({ allowObservers: true, maxObservers: 5 });
+    expect(s.join({ agentId: 'obs1', requestedRole: 'observer' })).toBe(true);
+  });
+  it('observer not counted in getMemberCount', () => {
+    const s = make({ allowObservers: true });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'obs1', requestedRole: 'observer' });
+    expect(s.getMemberCount()).toBe(1); // only non-observer
+  });
+  it('observer join blocked when allowObservers=false', () => {
+    const s = make({ allowObservers: false });
+    expect(s.join({ agentId: 'obs1', requestedRole: 'observer' })).toBe(false);
+  });
+  it('observer join blocked when maxObservers reached', () => {
+    const s = make({ allowObservers: true, maxObservers: 1 });
+    s.join({ agentId: 'obs1', requestedRole: 'observer' });
+    expect(s.join({ agentId: 'obs2', requestedRole: 'observer' })).toBe(false);
+  });
+});
+
+describe('SwarmMembership — approval workflow', () => {
+  it('join pending when requireApprovalToJoin=true and leader present', () => {
+    const s = make({ requireApprovalToJoin: true });
+    s.join({ agentId: 'leader' }); // auto-leader
+    const result = s.join({ agentId: 'newcomer' });
+    expect(result).toBe(false);
+    expect(s.getPendingJoins()).toHaveLength(1);
+    expect(s.getPendingJoins()[0].agentId).toBe('newcomer');
+  });
+  it('approveJoin by leader succeeds', () => {
+    const s = make({ requireApprovalToJoin: true, quorum: { minimumSize: 1 } });
+    s.join({ agentId: 'leader' });
+    s.join({ agentId: 'newcomer' });
+    expect(s.approveJoin('leader', 'newcomer')).toBe(true);
+    expect(s.getMemberCount()).toBe(2);
+  });
+  it('approveJoin by non-leader fails', () => {
+    const s = make({ requireApprovalToJoin: true });
+    s.join({ agentId: 'leader' });
+    s.join({ agentId: 'a2' });
+    s.join({ agentId: 'newcomer' });
+    expect(s.approveJoin('a2', 'newcomer')).toBe(false);
+  });
+  it('approveJoin for non-pending fails', () => {
+    const s = make({ requireApprovalToJoin: true });
+    s.join({ agentId: 'leader' });
+    expect(s.approveJoin('leader', 'ghost')).toBe(false);
+  });
+});
+
+describe('SwarmMembership — changeRole', () => {
+  it('changeRole to leader updates leaderId', () => {
+    const s = make({ quorum: { minimumSize: 1 } });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    s.changeRole('a2', 'leader');
+    expect(s.getLeader()?.agentId).toBe('a2');
+  });
+  it('old leader demoted to member when new leader elected', () => {
+    const s = make({ quorum: { minimumSize: 1 } });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    s.changeRole('a2', 'leader');
+    expect(s.getMember('a1')?.role).toBe('member');
+  });
+  it('changeRole returns false for unknown agent', () => {
+    const s = make();
+    expect(s.changeRole('ghost', 'member')).toBe(false);
+  });
+});
+
+describe('SwarmMembership — heartbeat & timeouts', () => {
+  it('heartbeat updates lastHeartbeat', () => {
+    const s = make();
+    s.join({ agentId: 'a1' });
+    const before = s.getMember('a1')!.lastHeartbeat;
+    s.heartbeat('a1');
+    expect(s.getMember('a1')!.lastHeartbeat).toBeGreaterThanOrEqual(before);
+  });
+  it('heartbeat reactivates inactive member', async () => {
+    const s = make({ heartbeatTimeoutMs: 1 });
+    s.join({ agentId: 'a1' });
+    await new Promise((r) => setTimeout(r, 5)); // let timeout expire
+    s.checkTimeouts(); // marks inactive
+    s.heartbeat('a1');
+    expect(s.getMember('a1')?.status).toBe('active');
+  });
+  it('checkTimeouts returns timed-out IDs', async () => {
+    const s = make({ heartbeatTimeoutMs: 1 });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    await new Promise((r) => setTimeout(r, 5)); // let timeout expire
+    const timedOut = s.checkTimeouts();
+    expect(timedOut).toContain('a1');
+    expect(timedOut).toContain('a2');
+  });
+  it('non-timed-out members not included', () => {
+    const s = make({ heartbeatTimeoutMs: 999999 });
+    s.join({ agentId: 'a1' });
+    expect(s.checkTimeouts()).toHaveLength(0);
+  });
+});
+
+describe('SwarmMembership — events', () => {
+  it('emits joined event on join', () => {
+    const s = make();
+    const events: string[] = [];
+    s.onEvent((e) => events.push(e.type));
+    s.join({ agentId: 'a1' });
+    expect(events).toContain('joined');
+  });
+  it('emits left event on leave', () => {
+    const s = make({ quorum: { minimumSize: 1 } });
+    const events: string[] = [];
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    s.onEvent((e) => events.push(e.type));
+    s.leave({ agentId: 'a2', graceful: true });
+    expect(events).toContain('left');
+  });
+  it('emits quorum-gained when threshold reached', () => {
+    // quorum requires 3 (ceil(5*0.5)=3 effective) by default
+    const events: string[] = [];
+    const s = make();
+    s.onEvent((e) => events.push(e.type));
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'a2' });
+    s.join({ agentId: 'a3' });
+    expect(events).toContain('quorum-gained');
+  });
+  it('unsubscribe returned function removes handler', () => {
+    const s = make();
+    const events: string[] = [];
+    const unsub = s.onEvent((e) => events.push(e.type));
+    unsub();
+    s.join({ agentId: 'a1' });
+    expect(events).toHaveLength(0);
+  });
+});
+
+describe('SwarmMembership — getActiveMembers / getMembers', () => {
+  it('getMembers includes all roles', () => {
+    const s = make({ allowObservers: true });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'obs1', requestedRole: 'observer' });
+    expect(s.getMembers()).toHaveLength(2);
+  });
+  it('getActiveMembers excludes observers and inactive', async () => {
+    const s = make({ allowObservers: true, heartbeatTimeoutMs: 1 });
+    s.join({ agentId: 'a1' });
+    s.join({ agentId: 'obs1', requestedRole: 'observer' });
+    await new Promise((r) => setTimeout(r, 5)); // let timeout expire
+    s.checkTimeouts(); // marks a1 inactive
+    expect(s.getActiveMembers()).toHaveLength(0);
+  });
+});