@holoscript/framework 6.0.3

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

@@ -0,0 +1,164 @@
+import { describe, it, expect } from 'vitest';
+import { ACOEngine, type ACOConfig } from '../ACOEngine';
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function mkACO(cfg?: Partial<ACOConfig>) {
+  return new ACOEngine(cfg);
+}
+
+/** Build an NxN distance matrix with given cost between all pairs */
+function uniformMatrix(n: number, cost = 1): number[][] {
+  return Array.from({ length: n }, (_, i) =>
+    Array.from({ length: n }, (_, j) => (i === j ? 0 : cost))
+  );
+}
+
+/** Build an asymmetric matrix where path 0→1→2→...→n-1 is cheapest */
+function directedMatrix(n: number): number[][] {
+  const m = uniformMatrix(n, 100); // default high cost
+  for (let i = 0; i < n - 1; i++) {
+    m[i][i + 1] = 1; // cheap forward path
+    m[i + 1][i] = 1; // and reverse for symmetric support
+  }
+  return m;
+}
+
+// ─── tests ───────────────────────────────────────────────────────────────────
+
+describe('ACOEngine — construction / defaultConfig', () => {
+  it('creates with empty config', () => expect(() => mkACO()).not.toThrow());
+  it('creates with partial config', () => {
+    expect(() => mkACO({ antCount: 5, maxIterations: 5 })).not.toThrow();
+  });
+});
+
+describe('ACOEngine — getRecommendedAntCount', () => {
+  const aco = mkACO();
+  it('returns min 10 for small node count', () => {
+    expect(aco.getRecommendedAntCount(2)).toBeGreaterThanOrEqual(10);
+  });
+  it('returns max 50 for large node count', () => {
+    expect(aco.getRecommendedAntCount(200)).toBeLessThanOrEqual(50);
+  });
+  it('roughly equals node count in mid range', () => {
+    expect(aco.getRecommendedAntCount(25)).toBe(25);
+  });
+  it('returns integer', () => {
+    const r = aco.getRecommendedAntCount(15);
+    expect(r).toBe(Math.round(r));
+  });
+});
+
+describe('ACOEngine — optimize result shape', () => {
+  it('returns all required fields', async () => {
+    const aco = mkACO({ antCount: 3, maxIterations: 3 });
+    const result = await aco.optimize(3, uniformMatrix(3));
+    expect(result).toHaveProperty('bestPath');
+    expect(result).toHaveProperty('bestCost');
+    expect(result).toHaveProperty('converged');
+    expect(result).toHaveProperty('iterations');
+    expect(result).toHaveProperty('costHistory');
+  });
+  it('bestPath length equals node count', async () => {
+    const n = 4;
+    const aco = mkACO({ antCount: 3, maxIterations: 3 });
+    const result = await aco.optimize(n, uniformMatrix(n));
+    expect(result.bestPath).toHaveLength(n);
+  });
+  it('bestPath visits each node exactly once', async () => {
+    const n = 5;
+    const aco = mkACO({ antCount: 5, maxIterations: 5 });
+    const result = await aco.optimize(n, uniformMatrix(n));
+    const sorted = [...result.bestPath].sort((a, b) => a - b);
+    expect(sorted).toEqual([0, 1, 2, 3, 4]);
+  });
+  it('iterations > 0', async () => {
+    const aco = mkACO({ antCount: 3, maxIterations: 5 });
+    const result = await aco.optimize(3, uniformMatrix(3));
+    expect(result.iterations).toBeGreaterThan(0);
+  });
+  it('costHistory is non-empty array', async () => {
+    const aco = mkACO({ antCount: 3, maxIterations: 3 });
+    const result = await aco.optimize(3, uniformMatrix(3));
+    expect(Array.isArray(result.costHistory)).toBe(true);
+    expect(result.costHistory.length).toBeGreaterThan(0);
+  });
+  it('bestCost equals min of costHistory', async () => {
+    const aco = mkACO({ antCount: 5, maxIterations: 5 });
+    const result = await aco.optimize(3, uniformMatrix(3, 2));
+    const minHistory = Math.min(...result.costHistory);
+    expect(result.bestCost).toBeCloseTo(minHistory, 9);
+  });
+  it('bestCost is a finite positive number', async () => {
+    const aco = mkACO({ antCount: 3, maxIterations: 3 });
+    const result = await aco.optimize(4, uniformMatrix(4));
+    expect(isFinite(result.bestCost)).toBe(true);
+    expect(result.bestCost).toBeGreaterThan(0);
+  });
+  it('converged = boolean', async () => {
+    const aco = mkACO({ antCount: 3, maxIterations: 3 });
+    const result = await aco.optimize(3, uniformMatrix(3));
+    expect(typeof result.converged).toBe('boolean');
+  });
+});
+
+describe('ACOEngine — convergence behavior', () => {
+  it('converges on uniform matrix in many iterations', async () => {
+    // With uniform costs and many iterations, ACO should converge
+    const aco = mkACO({ antCount: 10, maxIterations: 50, convergenceThreshold: 0.001 });
+    const result = await aco.optimize(3, uniformMatrix(3));
+    expect(result.converged).toBe(true);
+  });
+  it('does not converge with only 5 iterations (needs > 10)', async () => {
+    const aco = mkACO({ antCount: 5, maxIterations: 5 });
+    const result = await aco.optimize(4, uniformMatrix(4));
+    expect(result.converged).toBe(false);
+  });
+});
+
+describe('ACOEngine — path quality', () => {
+  it('finds the low-cost path in a directed matrix', async () => {
+    // For directed matrix, 0→1→2→3 costs 3 (each edge=1), any other cost=100
+    const n = 4;
+    const aco = mkACO({ antCount: 20, maxIterations: 30 });
+    const result = await aco.optimize(n, directedMatrix(n));
+    // The best path cost should be n-1 (consecutive edges at cost 1)
+    expect(result.bestCost).toBeLessThanOrEqual(n - 1 + 0.01); // allow float rounding
+  });
+  it('single node — bestPath is [0], bestCost = 0', async () => {
+    const aco = mkACO({ antCount: 2, maxIterations: 2 });
+    const result = await aco.optimize(1, [[0]]);
+    expect(result.bestPath).toEqual([0]);
+    expect(result.bestCost).toBe(0);
+  });
+  it('two nodes — bestPath visits both', async () => {
+    const aco = mkACO({ antCount: 3, maxIterations: 3 });
+    const result = await aco.optimize(2, [
+      [0, 5],
+      [5, 0],
+    ]);
+    expect(result.bestPath).toHaveLength(2);
+    expect(new Set(result.bestPath).size).toBe(2);
+  });
+});
+
+describe('ACOEngine — config sensitivity', () => {
+  it('high evaporation rate does not crash', async () => {
+    const aco = mkACO({ evaporationRate: 0.9, antCount: 3, maxIterations: 3 });
+    await expect(aco.optimize(3, uniformMatrix(3))).resolves.toBeDefined();
+  });
+  it('low alpha (pheromone ignored) does not crash', async () => {
+    const aco = mkACO({ alpha: 0.01, antCount: 3, maxIterations: 3 });
+    await expect(aco.optimize(3, uniformMatrix(3))).resolves.toBeDefined();
+  });
+  it('high elitistWeight does not crash', async () => {
+    const aco = mkACO({ elitistWeight: 10, antCount: 3, maxIterations: 3 });
+    await expect(aco.optimize(3, uniformMatrix(3))).resolves.toBeDefined();
+  });
+  it('large antCount works correctly', async () => {
+    const aco = mkACO({ antCount: 50, maxIterations: 3 });
+    const result = await aco.optimize(4, uniformMatrix(4));
+    expect(result.bestPath).toHaveLength(4);
+  });
+});

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

@@ -0,0 +1,117 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ACOEngine, type ACOConfig } from '../ACOEngine';
+
+describe('ACOEngine', () => {
+  let engine: ACOEngine;
+
+  beforeEach(() => {
+    engine = new ACOEngine();
+  });
+
+  describe('constructor', () => {
+    it('should create with default config', () => {
+      expect(engine).toBeDefined();
+    });
+
+    it('should accept custom config', () => {
+      const customConfig: Partial<ACOConfig> = {
+        antCount: 30,
+        maxIterations: 150,
+        alpha: 1.5,
+      };
+      const customEngine = new ACOEngine(customConfig);
+      expect(customEngine).toBeDefined();
+    });
+  });
+
+  describe('optimize', () => {
+    it('should find path through all nodes', async () => {
+      const nodes = 5;
+      // Simple distance matrix
+      const distanceMatrix = Array.from({ length: nodes }, (_, i) =>
+        Array.from({ length: nodes }, (_, j) => (i === j ? 0 : Math.abs(i - j)))
+      );
+
+      const result = await engine.optimize(nodes, distanceMatrix);
+
+      expect(result.bestPath).toHaveLength(nodes);
+      expect(new Set(result.bestPath).size).toBe(nodes); // All unique
+    });
+
+    it('should find optimal path for simple TSP', async () => {
+      // 4 nodes in a line: 0-1-2-3
+      // Optimal path: 0,1,2,3 or reverse (cost = 3)
+      const distanceMatrix = [
+        [0, 1, 2, 3],
+        [1, 0, 1, 2],
+        [2, 1, 0, 1],
+        [3, 2, 1, 0],
+      ];
+
+      const result = await engine.optimize(4, distanceMatrix);
+
+      // Should find a reasonably good path
+      expect(result.bestCost).toBeLessThanOrEqual(6); // Worst case is 6
+    });
+
+    it('should improve over iterations', async () => {
+      const nodes = 6;
+      const distanceMatrix = Array.from({ length: nodes }, () =>
+        Array.from({ length: nodes }, () => Math.random() * 10)
+      );
+      // Zero diagonal
+      for (let i = 0; i < nodes; i++) {
+        distanceMatrix[i][i] = 0;
+      }
+
+      const result = await engine.optimize(nodes, distanceMatrix);
+
+      expect(result.costHistory.length).toBeGreaterThan(1);
+      // Later costs should be <= earlier costs (or equal)
+      const firstCost = result.costHistory[0];
+      const lastCost = result.costHistory[result.costHistory.length - 1];
+      expect(lastCost).toBeLessThanOrEqual(firstCost);
+    });
+
+    it('should detect convergence', async () => {
+      // Uniform distances - should converge quickly
+      const nodes = 4;
+      const distanceMatrix = Array.from({ length: nodes }, (_, i) =>
+        Array.from({ length: nodes }, (_, j) => (i === j ? 0 : 1))
+      );
+
+      const result = await engine.optimize(nodes, distanceMatrix);
+
+      expect(result.converged || result.iterations >= 10).toBe(true);
+    });
+
+    it('should handle asymmetric distances', async () => {
+      const distanceMatrix = [
+        [0, 1, 5],
+        [5, 0, 1],
+        [1, 5, 0],
+      ];
+
+      const result = await engine.optimize(3, distanceMatrix);
+
+      expect(result.bestPath).toHaveLength(3);
+      expect(result.bestCost).toBeGreaterThan(0);
+    });
+  });
+
+  describe('getRecommendedAntCount', () => {
+    it('should return at least 10 for small problems', () => {
+      expect(engine.getRecommendedAntCount(3)).toBeGreaterThanOrEqual(10);
+    });
+
+    it('should cap at 50 for large problems', () => {
+      expect(engine.getRecommendedAntCount(100)).toBeLessThanOrEqual(50);
+    });
+
+    it('should scale with node count', () => {
+      const small = engine.getRecommendedAntCount(5);
+      const large = engine.getRecommendedAntCount(30);
+      expect(large).toBeGreaterThanOrEqual(small);
+    });
+  });
+});

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

@@ -0,0 +1,296 @@
+/**
+ * CollectiveIntelligence — Production Tests
+ */
+import { describe, it, expect } from 'vitest';
+import { CollectiveIntelligence } from '../CollectiveIntelligence';
+import type { IHiveContribution } from '@holoscript/core';
+
+function make(cfg = {}) {
+  return new CollectiveIntelligence(cfg);
+}
+
+function contrib(type: IHiveContribution['type'], content: string, confidence = 0.8) {
+  return { agentId: 'a1', type, content, confidence } as Omit<
+    IHiveContribution,
+    'id' | 'timestamp'
+  >;
+}
+
+describe('CollectiveIntelligence — createSession', () => {
+  it('creates session with id', () => {
+    const ci = make();
+    const s = ci.createSession('topic', 'goal', 'a1');
+    expect(s.id).toBeTruthy();
+    expect(s.id.startsWith('hive-')).toBe(true);
+  });
+  it('session has correct topic/goal/initiator', () => {
+    const ci = make();
+    const s = ci.createSession('AI safety', 'solve it', 'a1');
+    expect(s.topic).toBe('AI safety');
+    expect(s.goal).toBe('solve it');
+    expect(s.initiator).toBe('a1');
+  });
+  it('session status=active', () => {
+    const ci = make();
+    expect(ci.createSession('t', 'g', 'a1').status).toBe('active');
+  });
+  it('initiator is a participant', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    expect(s.participants).toContain('a1');
+  });
+  it('contributions starts empty', () => {
+    const ci = make();
+    expect(ci.createSession('t', 'g', 'a1').contributions).toHaveLength(0);
+  });
+  it('getSession returns created session', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    expect(ci.getSession(s.id)).toBe(s);
+  });
+  it('getSession unknown=undefined', () => {
+    expect(make().getSession('ghost')).toBeUndefined();
+  });
+  it('getActiveSessions includes new session', () => {
+    const ci = make();
+    ci.createSession('t', 'g', 'a1');
+    expect(ci.getActiveSessions()).toHaveLength(1);
+  });
+});
+
+describe('CollectiveIntelligence — join / leave', () => {
+  it('join adds participant', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.join(s.id, 'a2');
+    expect(ci.getSession(s.id)!.participants).toContain('a2');
+  });
+  it('join idempotent for duplicate', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.join(s.id, 'a1'); // already there
+    expect(ci.getSession(s.id)!.participants).toHaveLength(1);
+  });
+  it('join unknown session throws', () => {
+    expect(() => make().join('ghost', 'a1')).toThrow();
+  });
+  it('join full session throws', () => {
+    const ci = make({ maxParticipants: 1 });
+    const s = ci.createSession('t', 'g', 'a1');
+    expect(() => ci.join(s.id, 'a2')).toThrow();
+  });
+  it('leave removes participant', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.join(s.id, 'a2');
+    ci.leave(s.id, 'a2');
+    expect(ci.getSession(s.id)!.participants).not.toContain('a2');
+  });
+  it('leave unknown session throws', () => {
+    expect(() => make().leave('ghost', 'a1')).toThrow();
+  });
+});
+
+describe('CollectiveIntelligence — contribute', () => {
+  it('returns IHiveContribution with id/timestamp', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    const c = ci.contribute(s.id, contrib('idea', 'use caching'));
+    expect(c.id).toBeTruthy();
+    expect(c.timestamp).toBeGreaterThan(0);
+  });
+  it('contribution stored in session', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.contribute(s.id, contrib('idea', 'scale'));
+    expect(ci.getSession(s.id)!.contributions).toHaveLength(1);
+  });
+  it('non-participant cannot contribute', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    expect(() =>
+      ci.contribute(s.id, { agentId: 'stranger', type: 'idea', content: 'x', confidence: 0.5 })
+    ).toThrow();
+  });
+  it('contribute unknown session throws', () => {
+    expect(() => make().contribute('ghost', contrib('idea', 'x'))).toThrow();
+  });
+  it('getAgentContributions returns only that agent', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.join(s.id, 'a2');
+    ci.contribute(s.id, contrib('idea', 'c1'));
+    ci.contribute(s.id, { agentId: 'a2', type: 'critique', content: 'c2', confidence: 0.7 });
+    expect(ci.getAgentContributions(s.id, 'a1')).toHaveLength(1);
+  });
+  it('contribute to closed session throws', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.closeSession(s.id);
+    expect(() => ci.contribute(s.id, contrib('idea', 'x'))).toThrow();
+  });
+});
+
+describe('CollectiveIntelligence — vote', () => {
+  it('vote does not throw', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.join(s.id, 'a2');
+    const c = ci.contribute(s.id, contrib('idea', 'scale'));
+    expect(() => ci.vote(s.id, c.id, 'a2', 'support')).not.toThrow();
+  });
+  it('non-participant cannot vote', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    const c = ci.contribute(s.id, contrib('idea', 'scale'));
+    expect(() => ci.vote(s.id, c.id, 'outsider', 'support')).toThrow();
+  });
+  it('vote on unknown session throws', () => {
+    expect(() => make().vote('ghost', 'c1', 'a1', 'support')).toThrow();
+  });
+  it('getVotingResults returns array for valid session', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.contribute(s.id, contrib('idea', 'scale'));
+    const results = ci.getVotingResults(s.id);
+    expect(Array.isArray(results)).toBe(true);
+  });
+  it('getTopContribution returns highest voted', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.join(s.id, 'a2');
+    const c1 = ci.contribute(s.id, contrib('idea', 'best idea'));
+    const c2 = ci.contribute(s.id, {
+      agentId: 'a2',
+      type: 'idea',
+      content: 'other',
+      confidence: 0.5,
+    });
+    ci.vote(s.id, c1.id, 'a2', 'support');
+    const top = ci.getTopContribution(s.id);
+    expect(top?.id).toBe(c1.id);
+  });
+});
+
+describe('CollectiveIntelligence — synthesize', () => {
+  it('returns empty result when below synthesisMinContributions', () => {
+    const ci = make({ synthesisMinContributions: 3 });
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.contribute(s.id, contrib('idea', 'x'));
+    const r = ci.synthesize(s.id);
+    expect(r.confidence).toBe(0);
+    expect(r.synthesizedContent).toBe('');
+  });
+  it('returns non-empty when min contributions met', () => {
+    const ci = make({ synthesisMinContributions: 2 });
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.contribute(s.id, contrib('idea', 'implement caching layer'));
+    ci.contribute(s.id, contrib('solution', 'use Redis for cache'));
+    const r = ci.synthesize(s.id);
+    expect(r.synthesizedContent.length).toBeGreaterThan(0);
+    expect(r.confidence).toBeGreaterThan(0);
+  });
+  it('synthesize unknown session throws', () => {
+    expect(() => make().synthesize('ghost')).toThrow();
+  });
+  it('metadata totals correct', () => {
+    const ci = make({ synthesisMinContributions: 2 });
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.contribute(s.id, contrib('idea', 'an idea'));
+    ci.contribute(s.id, contrib('solution', 'a solution'));
+    const r = ci.synthesize(s.id);
+    expect(r.metadata.totalContributions).toBe(2);
+    expect(r.metadata.ideaCount).toBe(1);
+    expect(r.metadata.solutionCount).toBe(1);
+  });
+});
+
+describe('CollectiveIntelligence — resolve / closeSession', () => {
+  it('resolve sets session status=resolved', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.resolve(s.id, 'final decision');
+    expect(ci.getSession(s.id)!.status).toBe('resolved');
+    expect(ci.getSession(s.id)!.resolution).toBe('final decision');
+  });
+  it('resolve unknown session throws', () => {
+    expect(() => make().resolve('ghost', 'x')).toThrow();
+  });
+  it('closeSession sets status=closed', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.closeSession(s.id);
+    expect(ci.getSession(s.id)!.status).toBe('closed');
+  });
+  it('closeSession unknown session throws', () => {
+    expect(() => make().closeSession('ghost')).toThrow();
+  });
+  it('resolved session not in getActiveSessions', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.resolve(s.id, 'done');
+    expect(ci.getActiveSessions()).toHaveLength(0);
+  });
+});
+
+describe('CollectiveIntelligence — getSessionStats', () => {
+  it('returns undefined for unknown session', () => {
+    expect(make().getSessionStats('ghost')).toBeUndefined();
+  });
+  it('returns correct participantCount and contributionCount', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.join(s.id, 'a2');
+    ci.contribute(s.id, contrib('idea', 'x'));
+    const stats = ci.getSessionStats(s.id)!;
+    expect(stats.participantCount).toBe(2);
+    expect(stats.contributionCount).toBe(1);
+  });
+  it('contributionsByType correct', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.contribute(s.id, contrib('idea', 'x'));
+    ci.contribute(s.id, contrib('critique', 'y'));
+    const stats = ci.getSessionStats(s.id)!;
+    expect(stats.contributionsByType.idea).toBe(1);
+    expect(stats.contributionsByType.critique).toBe(1);
+  });
+  it('averageConfidence computed', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    ci.contribute(s.id, contrib('idea', 'x', 0.6));
+    ci.contribute(s.id, contrib('idea', 'y', 0.8));
+    const stats = ci.getSessionStats(s.id)!;
+    expect(stats.averageConfidence).toBeCloseTo(0.7, 5);
+  });
+});
+
+describe('CollectiveIntelligence — checkForConsensus', () => {
+  it('returns false for empty session', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    expect(ci.checkForConsensus(s.id)).toBe(false);
+  });
+  it('checkForConsensus unknown session returns false', () => {
+    expect(make().checkForConsensus('ghost')).toBe(false);
+  });
+});
+
+describe('CollectiveIntelligence — findSimilarContributions', () => {
+  it('returns empty for unknown session', () => {
+    expect(make().findSimilarContributions('ghost', 'c1')).toHaveLength(0);
+  });
+  it('returns empty for unknown contribution', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    expect(ci.findSimilarContributions(s.id, 'ghost')).toHaveLength(0);
+  });
+  it('finds similar contributions by content overlap', () => {
+    const ci = make();
+    const s = ci.createSession('t', 'g', 'a1');
+    const c1 = ci.contribute(s.id, contrib('idea', 'implement redis caching system'));
+    ci.contribute(s.id, contrib('idea', 'setup redis caching service'));
+    const similar = ci.findSimilarContributions(s.id, c1.id);
+    expect(similar.length).toBeGreaterThanOrEqual(0); // may or may not find based on jaccard threshold
+  });
+});