@holoscript/framework 6.0.3

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

@@ -0,0 +1,264 @@
+/**
+ * SwarmMembership Tests
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { SwarmMembership, type MembershipEvent } from '../SwarmMembership';
+
+describe('SwarmMembership', () => {
+  let membership: SwarmMembership;
+
+  beforeEach(() => {
+    membership = new SwarmMembership({
+      quorum: { minimumSize: 2, optimalSize: 5, maximumSize: 10 },
+    });
+  });
+
+  describe('join', () => {
+    it('should allow first agent to join as leader', () => {
+      const success = membership.join({ agentId: 'agent-1' });
+      expect(success).toBe(true);
+
+      const member = membership.getMember('agent-1');
+      expect(member?.role).toBe('leader');
+    });
+
+    it('should allow subsequent agents to join as members', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+
+      const member = membership.getMember('agent-2');
+      expect(member?.role).toBe('member');
+    });
+
+    it('should return true for already joined agent', () => {
+      membership.join({ agentId: 'agent-1' });
+      const success = membership.join({ agentId: 'agent-1' });
+      expect(success).toBe(true);
+    });
+
+    it('should prevent joining at maximum', () => {
+      membership = new SwarmMembership({
+        quorum: { minimumSize: 1, optimalSize: 2, maximumSize: 2 },
+      });
+
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+      const success = membership.join({ agentId: 'agent-3' });
+
+      expect(success).toBe(false);
+    });
+
+    it('should add pending when approval required', () => {
+      membership = new SwarmMembership({ requireApprovalToJoin: true });
+      membership.join({ agentId: 'leader' });
+
+      const success = membership.join({ agentId: 'agent-2' });
+      expect(success).toBe(false);
+
+      const pending = membership.getPendingJoins();
+      expect(pending).toHaveLength(1);
+      expect(pending[0].agentId).toBe('agent-2');
+    });
+  });
+
+  describe('approveJoin', () => {
+    it('should allow leader to approve pending join', () => {
+      membership = new SwarmMembership({ requireApprovalToJoin: true });
+      membership.join({ agentId: 'leader' });
+      membership.join({ agentId: 'agent-2' });
+
+      const success = membership.approveJoin('leader', 'agent-2');
+      expect(success).toBe(true);
+      expect(membership.getMember('agent-2')).toBeDefined();
+    });
+
+    it('should reject approval from non-leader', () => {
+      membership = new SwarmMembership({ requireApprovalToJoin: true });
+      membership.join({ agentId: 'leader' });
+      membership.join({ agentId: 'agent-2' });
+
+      const success = membership.approveJoin('agent-2', 'agent-2');
+      expect(success).toBe(false);
+    });
+  });
+
+  describe('leave', () => {
+    it('should remove member', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+      membership.join({ agentId: 'agent-3' });
+
+      membership.leave({ agentId: 'agent-2', graceful: true });
+      expect(membership.getMember('agent-2')).toBeUndefined();
+    });
+
+    it('should elect new leader when leader leaves', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+      membership.join({ agentId: 'agent-3' });
+
+      expect(membership.getLeader()?.agentId).toBe('agent-1');
+      membership.leave({ agentId: 'agent-1', graceful: true });
+
+      expect(membership.getLeader()).toBeDefined();
+      expect(membership.getLeader()?.agentId).not.toBe('agent-1');
+    });
+
+    it('should prevent leaving below minimum', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+
+      const success = membership.leave({ agentId: 'agent-2', graceful: true });
+      expect(success).toBe(false);
+
+      const member = membership.getMember('agent-2');
+      expect(member?.status).toBe('leaving');
+    });
+  });
+
+  describe('observers', () => {
+    it('should allow observers to join', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'observer-1', requestedRole: 'observer' });
+
+      const observer = membership.getMember('observer-1');
+      expect(observer?.role).toBe('observer');
+    });
+
+    it('should not count observers in member count', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'observer-1', requestedRole: 'observer' });
+
+      expect(membership.getMemberCount()).toBe(1);
+    });
+
+    it('should enforce max observers', () => {
+      membership = new SwarmMembership({ maxObservers: 1 });
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'observer-1', requestedRole: 'observer' });
+
+      const success = membership.join({ agentId: 'observer-2', requestedRole: 'observer' });
+      expect(success).toBe(false);
+    });
+
+    it('should allow disabling observers', () => {
+      membership = new SwarmMembership({ allowObservers: false });
+      membership.join({ agentId: 'agent-1' });
+
+      const success = membership.join({ agentId: 'observer-1', requestedRole: 'observer' });
+      expect(success).toBe(false);
+    });
+  });
+
+  describe('heartbeat', () => {
+    it('should update last heartbeat', async () => {
+      membership.join({ agentId: 'agent-1' });
+      const before = membership.getMember('agent-1')?.lastHeartbeat;
+
+      // Wait a bit for timestamp to change
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      membership.heartbeat('agent-1');
+
+      const after = membership.getMember('agent-1')?.lastHeartbeat;
+      expect(after).toBeGreaterThanOrEqual(before!);
+    });
+  });
+
+  describe('changeRole', () => {
+    it('should change member role', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+
+      membership.changeRole('agent-2', 'leader');
+
+      expect(membership.getMember('agent-2')?.role).toBe('leader');
+      expect(membership.getMember('agent-1')?.role).toBe('member');
+      expect(membership.getLeader()?.agentId).toBe('agent-2');
+    });
+  });
+
+  describe('getMembers', () => {
+    it('should return all members', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+      membership.join({ agentId: 'observer-1', requestedRole: 'observer' });
+
+      const all = membership.getMembers();
+      expect(all).toHaveLength(3);
+    });
+  });
+
+  describe('getActiveMembers', () => {
+    it('should filter out observers and inactive', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+      membership.join({ agentId: 'observer-1', requestedRole: 'observer' });
+
+      const active = membership.getActiveMembers();
+      expect(active).toHaveLength(2);
+      expect(active.find((m) => m.role === 'observer')).toBeUndefined();
+    });
+  });
+
+  describe('getQuorumState', () => {
+    it('should return quorum state', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+      membership.join({ agentId: 'agent-3' });
+
+      const state = membership.getQuorumState();
+      expect(state.currentSize).toBe(3);
+      expect(state.hasQuorum).toBe(true);
+    });
+  });
+
+  describe('events', () => {
+    it('should emit join events', () => {
+      const events: MembershipEvent[] = [];
+      membership.onEvent((e) => events.push(e));
+
+      membership.join({ agentId: 'agent-1' });
+
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe('joined');
+      expect(events[0].agentId).toBe('agent-1');
+    });
+
+    it('should emit leave events', () => {
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+      membership.join({ agentId: 'agent-3' });
+
+      const events: MembershipEvent[] = [];
+      membership.onEvent((e) => events.push(e));
+
+      membership.leave({ agentId: 'agent-2', graceful: true });
+
+      expect(events.some((e) => e.type === 'left' && e.agentId === 'agent-2')).toBe(true);
+    });
+
+    it('should emit quorum events', () => {
+      const events: MembershipEvent[] = [];
+      membership.onEvent((e) => events.push(e));
+
+      membership.join({ agentId: 'agent-1' });
+      membership.join({ agentId: 'agent-2' });
+      membership.join({ agentId: 'agent-3' });
+
+      expect(events.some((e) => e.type === 'quorum-gained')).toBe(true);
+    });
+
+    it('should allow unsubscribing', () => {
+      const events: MembershipEvent[] = [];
+      const unsub = membership.onEvent((e) => events.push(e));
+
+      membership.join({ agentId: 'agent-1' });
+      expect(events).toHaveLength(1);
+
+      unsub();
+      membership.join({ agentId: 'agent-2' });
+      expect(events).toHaveLength(1);
+    });
+  });
+});

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

@@ -0,0 +1,233 @@
+/**
+ * VotingRound.prod.test.ts
+ *
+ * Production tests for VotingRound — contribution registration, vote casting,
+ * duplicate detection, weighted scores, super-majority, winner selection,
+ * closed-state guards, and statistics.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { VotingRound } from '../VotingRound';
+import type { IHiveContribution } from '@holoscript/core';
+
+function makeContrib(id: string): IHiveContribution {
+  return {
+    id,
+    agentId: 'agent-1',
+    type: 'insight',
+    content: `Content ${id}`,
+    confidence: 0.9,
+    timestamp: Date.now(),
+  } as any;
+}
+
+describe('VotingRound', () => {
+  let round: VotingRound;
+
+  beforeEach(() => {
+    round = new VotingRound({ minVotesRequired: 2, superMajorityThreshold: 0.5 });
+  });
+
+  // -------------------------------------------------------------------------
+  // registerContribution
+  // -------------------------------------------------------------------------
+  describe('registerContribution()', () => {
+    it('registers a contribution', () => {
+      round.registerContribution(makeContrib('c1'));
+      expect(round.getResult('c1')).toBeDefined();
+    });
+
+    it('throws when round is closed', () => {
+      round.close();
+      expect(() => round.registerContribution(makeContrib('c1'))).toThrow('closed');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // castVote
+  // -------------------------------------------------------------------------
+  describe('castVote()', () => {
+    it('records a support vote', () => {
+      round.registerContribution(makeContrib('c1'));
+      round.castVote('c1', 'voter-a', 'support');
+      expect(round.getResult('c1')!.supportVotes).toBe(1);
+    });
+
+    it('records an oppose vote', () => {
+      round.registerContribution(makeContrib('c1'));
+      round.castVote('c1', 'voter-a', 'oppose');
+      expect(round.getResult('c1')!.opposeVotes).toBe(1);
+    });
+
+    it('throws on duplicate vote by same voter', () => {
+      round.registerContribution(makeContrib('c1'));
+      round.castVote('c1', 'voter-a', 'support');
+      expect(() => round.castVote('c1', 'voter-a', 'oppose')).toThrow('already voted');
+    });
+
+    it('throws for unregistered contribution', () => {
+      expect(() => round.castVote('ghost', 'voter-a', 'support')).toThrow();
+    });
+
+    it('throws when round is closed', () => {
+      round.registerContribution(makeContrib('c1'));
+      round.close();
+      expect(() => round.castVote('c1', 'voter-a', 'support')).toThrow('closed');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // getResult
+  // -------------------------------------------------------------------------
+  describe('getResult()', () => {
+    it('returns undefined for unknown contribution', () => {
+      expect(round.getResult('ghost')).toBeUndefined();
+    });
+
+    it('netScore = supportVotes - opposeVotes', () => {
+      round.registerContribution(makeContrib('c1'));
+      round.castVote('c1', 'a', 'support');
+      round.castVote('c1', 'b', 'support');
+      round.castVote('c1', 'c', 'oppose');
+      expect(round.getResult('c1')!.netScore).toBe(1);
+    });
+
+    it('voterIds contains all voters', () => {
+      round.registerContribution(makeContrib('c1'));
+      round.castVote('c1', 'a', 'support');
+      round.castVote('c1', 'b', 'oppose');
+      expect(round.getResult('c1')!.voterIds).toContain('a');
+      expect(round.getResult('c1')!.voterIds).toContain('b');
+    });
+
+    it('weightedScore uses voterConfidence when weightByConfidence=true', () => {
+      const r = new VotingRound({ weightByConfidence: true });
+      r.registerContribution(makeContrib('c1'));
+      r.castVote('c1', 'a', 'support', 0.8);
+      r.castVote('c1', 'b', 'support', 0.4);
+      expect(r.getResult('c1')!.weightedScore).toBeCloseTo(1.2, 5);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // getAllResults
+  // -------------------------------------------------------------------------
+  describe('getAllResults()', () => {
+    it('returns empty array when no contributions', () => {
+      expect(round.getAllResults()).toHaveLength(0);
+    });
+
+    it('sorted by weightedScore descending', () => {
+      round.registerContribution(makeContrib('a'));
+      round.registerContribution(makeContrib('b'));
+      round.castVote('a', 'v1', 'support');
+      round.castVote('a', 'v2', 'support');
+      round.castVote('b', 'v3', 'support');
+      const results = round.getAllResults();
+      expect(results[0].weightedScore).toBeGreaterThanOrEqual(results[1].weightedScore);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // hasSuperMajority
+  // -------------------------------------------------------------------------
+  describe('hasSuperMajority()', () => {
+    it('returns false with too few votes', () => {
+      round.registerContribution(makeContrib('c1'));
+      round.castVote('c1', 'a', 'support'); // only 1 vote, need 2
+      expect(round.hasSuperMajority('c1')).toBe(false);
+    });
+
+    it('returns true when support ratio >= threshold with enough votes', () => {
+      round.registerContribution(makeContrib('c1'));
+      round.castVote('c1', 'a', 'support');
+      round.castVote('c1', 'b', 'support'); // 2 support, 0 oppose, ratio=1.0 >= 0.5
+      expect(round.hasSuperMajority('c1')).toBe(true);
+    });
+
+    it('returns false when oppose outnumbers support below threshold', () => {
+      const r = new VotingRound({ minVotesRequired: 2, superMajorityThreshold: 0.7 });
+      r.registerContribution(makeContrib('c1'));
+      r.castVote('c1', 'a', 'support');
+      r.castVote('c1', 'b', 'oppose');
+      r.castVote('c1', 'c', 'oppose'); // 1/3 support < 0.7
+      expect(r.hasSuperMajority('c1')).toBe(false);
+    });
+
+    it('returns false for unknown contribution', () => {
+      expect(round.hasSuperMajority('ghost')).toBe(false);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // getApprovedContributions / getWinner
+  // -------------------------------------------------------------------------
+  describe('getApprovedContributions / getWinner', () => {
+    it('getApprovedContributions returns approved items', () => {
+      round.registerContribution(makeContrib('a'));
+      round.registerContribution(makeContrib('b'));
+      round.castVote('a', 'v1', 'support');
+      round.castVote('a', 'v2', 'support');
+      // b has no votes — not approved
+      const approved = round.getApprovedContributions();
+      expect(approved.map((c) => c.id)).toContain('a');
+      expect(approved.map((c) => c.id)).not.toContain('b');
+    });
+
+    it('getWinner returns top-scored contribution', () => {
+      round.registerContribution(makeContrib('a'));
+      round.registerContribution(makeContrib('b'));
+      round.castVote('a', 'v1', 'support');
+      round.castVote('a', 'v2', 'support');
+      round.castVote('b', 'v3', 'oppose');
+      expect(round.getWinner()!.id).toBe('a');
+    });
+
+    it('getWinner returns undefined when no contributions', () => {
+      expect(round.getWinner()).toBeUndefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // close / isClosed
+  // -------------------------------------------------------------------------
+  describe('close() / isClosed()', () => {
+    it('starts open', () => {
+      expect(round.isClosed()).toBe(false);
+    });
+    it('isClosed returns true after close()', () => {
+      round.close();
+      expect(round.isClosed()).toBe(true);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // getStatistics
+  // -------------------------------------------------------------------------
+  describe('getStatistics()', () => {
+    it('0 contributions: totalVotes=0', () => {
+      expect(round.getStatistics().totalVotes).toBe(0);
+    });
+
+    it('counts total contributions', () => {
+      round.registerContribution(makeContrib('a'));
+      round.registerContribution(makeContrib('b'));
+      expect(round.getStatistics().totalContributions).toBe(2);
+    });
+
+    it('counts total votes across all contributions', () => {
+      round.registerContribution(makeContrib('a'));
+      round.registerContribution(makeContrib('b'));
+      round.castVote('a', 'v1', 'support');
+      round.castVote('b', 'v2', 'oppose');
+      expect(round.getStatistics().totalVotes).toBe(2);
+    });
+
+    it('hasConsensus is true when winner has super-majority', () => {
+      round.registerContribution(makeContrib('a'));
+      round.castVote('a', 'v1', 'support');
+      round.castVote('a', 'v2', 'support');
+      expect(round.getStatistics().hasConsensus).toBe(true);
+    });
+  });
+});

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

@@ -0,0 +1,174 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { VotingRound } from '../VotingRound';
+import type { IHiveContribution } from '@holoscript/core';
+
+function contribution(id: string, agentId = 'agent-1'): IHiveContribution {
+  return {
+    id,
+    agentId,
+    timestamp: Date.now(),
+    type: 'idea',
+    content: `Idea ${id}`,
+    confidence: 0.8,
+  };
+}
+
+describe('VotingRound', () => {
+  let round: VotingRound;
+
+  beforeEach(() => {
+    round = new VotingRound();
+  });
+
+  it('starts open', () => {
+    expect(round.isClosed()).toBe(false);
+  });
+
+  it('registerContribution adds to round', () => {
+    round.registerContribution(contribution('c1'));
+    const stats = round.getStatistics();
+    expect(stats.totalContributions).toBe(1);
+  });
+
+  it('registerContribution throws when closed', () => {
+    round.close();
+    expect(() => round.registerContribution(contribution('c1'))).toThrow('closed');
+  });
+
+  it('castVote records vote', () => {
+    round.registerContribution(contribution('c1'));
+    round.castVote('c1', 'voter-1', 'support');
+    const r = round.getResult('c1');
+    expect(r?.supportVotes).toBe(1);
+    expect(r?.opposeVotes).toBe(0);
+  });
+
+  it('castVote throws when closed', () => {
+    round.registerContribution(contribution('c1'));
+    round.close();
+    expect(() => round.castVote('c1', 'voter-1', 'support')).toThrow('closed');
+  });
+
+  it('castVote throws for unregistered contribution', () => {
+    expect(() => round.castVote('nope', 'voter-1', 'support')).toThrow('not registered');
+  });
+
+  it('castVote throws on duplicate vote', () => {
+    round.registerContribution(contribution('c1'));
+    round.castVote('c1', 'voter-1', 'support');
+    expect(() => round.castVote('c1', 'voter-1', 'oppose')).toThrow('already voted');
+  });
+
+  it('oppose votes are counted', () => {
+    round.registerContribution(contribution('c1'));
+    round.castVote('c1', 'voter-1', 'oppose');
+    const r = round.getResult('c1');
+    expect(r?.opposeVotes).toBe(1);
+    expect(r?.netScore).toBe(-1);
+  });
+
+  it('weightByConfidence applies voter confidence as weight', () => {
+    round = new VotingRound({ weightByConfidence: true });
+    round.registerContribution(contribution('c1'));
+    round.castVote('c1', 'voter-1', 'support', 0.9);
+    round.castVote('c1', 'voter-2', 'oppose', 0.3);
+    const r = round.getResult('c1');
+    expect(r?.weightedScore).toBeCloseTo(0.6);
+  });
+
+  it('getResult returns undefined for unknown contribution', () => {
+    expect(round.getResult('nope')).toBeUndefined();
+  });
+
+  it('getAllResults sorts by weighted score', () => {
+    round.registerContribution(contribution('c1'));
+    round.registerContribution(contribution('c2'));
+    round.castVote('c1', 'v1', 'support');
+    round.castVote('c2', 'v1', 'support');
+    round.castVote('c2', 'v2', 'support');
+    const results = round.getAllResults();
+    expect(results[0].contributionId).toBe('c2');
+    expect(results[1].contributionId).toBe('c1');
+  });
+
+  it('hasSuperMajority returns true when threshold met', () => {
+    round = new VotingRound({ superMajorityThreshold: 0.5, minVotesRequired: 2 });
+    round.registerContribution(contribution('c1'));
+    round.castVote('c1', 'v1', 'support');
+    round.castVote('c1', 'v2', 'support');
+    expect(round.hasSuperMajority('c1')).toBe(true);
+  });
+
+  it('hasSuperMajority returns false below threshold', () => {
+    round = new VotingRound({ superMajorityThreshold: 0.67, minVotesRequired: 2 });
+    round.registerContribution(contribution('c1'));
+    round.castVote('c1', 'v1', 'support');
+    round.castVote('c1', 'v2', 'oppose');
+    expect(round.hasSuperMajority('c1')).toBe(false);
+  });
+
+  it('hasSuperMajority returns false below minVotesRequired', () => {
+    round = new VotingRound({ superMajorityThreshold: 0.5, minVotesRequired: 5 });
+    round.registerContribution(contribution('c1'));
+    round.castVote('c1', 'v1', 'support');
+    expect(round.hasSuperMajority('c1')).toBe(false);
+  });
+
+  it('hasSuperMajority returns false for unknown contribution', () => {
+    expect(round.hasSuperMajority('nope')).toBe(false);
+  });
+
+  it('getApprovedContributions returns approved only', () => {
+    round = new VotingRound({ superMajorityThreshold: 0.5, minVotesRequired: 2 });
+    round.registerContribution(contribution('c1'));
+    round.registerContribution(contribution('c2'));
+    round.castVote('c1', 'v1', 'support');
+    round.castVote('c1', 'v2', 'support');
+    round.castVote('c2', 'v1', 'oppose');
+    round.castVote('c2', 'v2', 'oppose');
+    const approved = round.getApprovedContributions();
+    expect(approved).toHaveLength(1);
+    expect(approved[0].id).toBe('c1');
+  });
+
+  it('getWinner returns top-ranked contribution', () => {
+    round.registerContribution(contribution('c1'));
+    round.registerContribution(contribution('c2'));
+    round.castVote('c1', 'v1', 'support');
+    round.castVote('c2', 'v1', 'support');
+    round.castVote('c2', 'v2', 'support');
+    expect(round.getWinner()?.id).toBe('c2');
+  });
+
+  it('getWinner returns undefined with no contributions', () => {
+    expect(round.getWinner()).toBeUndefined();
+  });
+
+  it('close prevents further voting', () => {
+    round.registerContribution(contribution('c1'));
+    round.close();
+    expect(round.isClosed()).toBe(true);
+    expect(() => round.castVote('c1', 'v1', 'support')).toThrow();
+  });
+
+  it('getStatistics returns correct stats', () => {
+    round = new VotingRound({ superMajorityThreshold: 0.5, minVotesRequired: 1 });
+    round.registerContribution(contribution('c1'));
+    round.registerContribution(contribution('c2'));
+    round.castVote('c1', 'v1', 'support');
+    round.castVote('c2', 'v1', 'support');
+    round.castVote('c2', 'v2', 'support');
+    const stats = round.getStatistics();
+    expect(stats.totalContributions).toBe(2);
+    expect(stats.totalVotes).toBe(3);
+    expect(stats.hasConsensus).toBe(true);
+  });
+
+  it('getStatistics empty round', () => {
+    const stats = round.getStatistics();
+    expect(stats.totalContributions).toBe(0);
+    expect(stats.totalVotes).toBe(0);
+    expect(stats.hasConsensus).toBe(false);
+    expect(stats.participationRate).toBe(0);
+  });
+});