@holoscript/framework 6.0.3

package/src/swarm/messaging/__tests__/GossipProtocol.test.ts

@@ -0,0 +1,437 @@
+/**
+ * GossipProtocol Tests
+ * HoloScript v3.2 - Autonomous Agent Swarms
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { GossipProtocol, AntiEntropySync } from '../GossipProtocol';
+
+describe('GossipProtocol', () => {
+  let protocol: GossipProtocol;
+
+  beforeEach(() => {
+    protocol = new GossipProtocol('node-1');
+  });
+
+  afterEach(() => {
+    protocol.stop();
+    vi.restoreAllMocks();
+  });
+
+  describe('lifecycle', () => {
+    it('should start the protocol', () => {
+      protocol.start();
+      expect(protocol.isRunning()).toBe(true);
+    });
+
+    it('should stop the protocol', () => {
+      protocol.start();
+      protocol.stop();
+      expect(protocol.isRunning()).toBe(false);
+    });
+
+    it('should not start twice', () => {
+      protocol.start();
+      protocol.start(); // Should not throw
+      expect(protocol.isRunning()).toBe(true);
+    });
+  });
+
+  describe('peer management', () => {
+    it('should add a peer', () => {
+      protocol.addPeer('peer-1', 'localhost:3001');
+
+      const peer = protocol.getPeer('peer-1');
+      expect(peer).toBeDefined();
+      expect(peer?.address).toBe('localhost:3001');
+    });
+
+    it('should not add self as peer', () => {
+      protocol.addPeer('node-1', 'localhost:3001');
+
+      expect(protocol.getAllPeers().length).toBe(0);
+    });
+
+    it('should remove a peer', () => {
+      protocol.addPeer('peer-1', 'localhost:3001');
+
+      const removed = protocol.removePeer('peer-1');
+
+      expect(removed).toBe(true);
+      expect(protocol.getPeer('peer-1')).toBeUndefined();
+    });
+
+    it('should get active peers', () => {
+      protocol.addPeer('peer-1', 'addr1');
+      protocol.addPeer('peer-2', 'addr2');
+
+      const peer2 = protocol.getPeer('peer-2')!;
+      peer2.isActive = false;
+
+      const active = protocol.getActivePeers();
+      expect(active.length).toBe(1);
+      expect(active[0].id).toBe('peer-1');
+    });
+
+    it('should store peer metadata', () => {
+      protocol.addPeer('peer-1', 'addr1', { region: 'us-west' });
+
+      const peer = protocol.getPeer('peer-1');
+      expect(peer?.metadata?.region).toBe('us-west');
+    });
+  });
+
+  describe('publishing', () => {
+    it('should publish a message', () => {
+      const msgId = protocol.publish({ data: 'test' });
+
+      expect(msgId).toContain('gossip-');
+      expect(msgId).toContain('node-1');
+    });
+
+    it('should emit locally on publish', () => {
+      const handler = vi.fn();
+      protocol.subscribe('data', handler);
+
+      protocol.publish({ data: 'test' });
+
+      expect(handler).toHaveBeenCalledOnce();
+    });
+
+    it('should publish with custom type', () => {
+      const handler = vi.fn();
+      protocol.subscribe('custom', handler);
+
+      protocol.publish({ x: 1 }, 'custom');
+
+      expect(handler).toHaveBeenCalled();
+      expect(handler.mock.calls[0][0].type).toBe('custom');
+    });
+
+    it('should track sent messages', () => {
+      protocol.publish({ data: 1 });
+      protocol.publish({ data: 2 });
+
+      const stats = protocol.getStats();
+      expect(stats.messagesSent).toBe(2);
+    });
+  });
+
+  describe('receiving', () => {
+    it('should receive a message', async () => {
+      const handler = vi.fn();
+      protocol.subscribe('data', handler);
+      protocol.addPeer('peer-1', 'addr');
+
+      const received = await protocol.receive(
+        {
+          id: 'msg-1',
+          originId: 'peer-1',
+          content: { data: 'incoming' },
+          type: 'data',
+          version: 1,
+          createdAt: Date.now(),
+          ttl: 30000,
+          hops: 0,
+          path: ['peer-1'],
+        },
+        'peer-1'
+      );
+
+      expect(received).toBe(true);
+      expect(handler).toHaveBeenCalledOnce();
+    });
+
+    it('should ignore duplicate messages', async () => {
+      const handler = vi.fn();
+      protocol.subscribe('data', handler);
+      protocol.addPeer('peer-1', 'addr');
+
+      const msg = {
+        id: 'msg-dup',
+        originId: 'peer-1',
+        content: { data: 'x' },
+        type: 'data' as const,
+        version: 1,
+        createdAt: Date.now(),
+        ttl: 30000,
+        hops: 0,
+        path: ['peer-1'],
+      };
+
+      await protocol.receive(msg, 'peer-1');
+      const secondReceive = await protocol.receive(msg, 'peer-1');
+
+      expect(secondReceive).toBe(false);
+      expect(handler).toHaveBeenCalledOnce();
+
+      const stats = protocol.getStats();
+      expect(stats.duplicatesIgnored).toBe(1);
+    });
+
+    it('should drop expired messages', async () => {
+      const handler = vi.fn();
+      protocol.subscribe('data', handler);
+
+      const received = await protocol.receive(
+        {
+          id: 'msg-exp',
+          originId: 'peer-1',
+          content: {},
+          type: 'data',
+          version: 1,
+          createdAt: Date.now() - 60000,
+          ttl: 30000, // Already expired
+          hops: 0,
+          path: ['peer-1'],
+        },
+        'peer-1'
+      );
+
+      expect(received).toBe(false);
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('should drop messages over hop limit', async () => {
+      const protocol10 = new GossipProtocol('node', { maxHops: 10 });
+      const handler = vi.fn();
+      protocol10.subscribe('data', handler);
+
+      const received = await protocol10.receive(
+        {
+          id: 'msg-hops',
+          originId: 'origin',
+          content: {},
+          type: 'data',
+          version: 1,
+          createdAt: Date.now(),
+          ttl: 30000,
+          hops: 15, // Over limit
+          path: Array(15).fill('node'),
+        },
+        'peer-1'
+      );
+
+      expect(received).toBe(false);
+      expect(handler).not.toHaveBeenCalled();
+      protocol10.stop();
+    });
+
+    it('should update peer last seen', async () => {
+      protocol.addPeer('peer-1', 'addr');
+      const before = protocol.getPeer('peer-1')!.lastSeen;
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      await protocol.receive(
+        {
+          id: 'msg-update',
+          originId: 'peer-1',
+          content: {},
+          type: 'data',
+          version: 1,
+          createdAt: Date.now(),
+          ttl: 30000,
+          hops: 0,
+          path: ['peer-1'],
+        },
+        'peer-1'
+      );
+
+      const after = protocol.getPeer('peer-1')!.lastSeen;
+      expect(after).toBeGreaterThan(before);
+    });
+  });
+
+  describe('subscription', () => {
+    it('should subscribe to specific type', () => {
+      const handler = vi.fn();
+      protocol.subscribe('heartbeat', handler);
+
+      protocol.publish({}, 'data');
+      protocol.publish({}, 'heartbeat');
+
+      expect(handler).toHaveBeenCalledOnce();
+    });
+
+    it('should support wildcard subscription', () => {
+      const handler = vi.fn();
+      protocol.subscribe('*', handler);
+
+      protocol.publish({}, 'data');
+      protocol.publish({}, 'heartbeat');
+
+      expect(handler).toHaveBeenCalledTimes(2);
+    });
+
+    it('should unsubscribe', () => {
+      const handler = vi.fn();
+      const unsub = protocol.subscribe('data', handler);
+
+      unsub();
+      protocol.publish({}, 'data');
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('heartbeat and membership', () => {
+    it('should publish heartbeat', () => {
+      const handler = vi.fn();
+      protocol.subscribe('heartbeat', handler);
+
+      const msgId = protocol.publishHeartbeat({ status: 'ok' });
+
+      expect(msgId).toBeDefined();
+      expect(handler).toHaveBeenCalledOnce();
+    });
+
+    it('should publish membership change', () => {
+      const handler = vi.fn();
+      protocol.subscribe('membership', handler);
+
+      protocol.publishMembership('join', { group: 'swarm-1' });
+
+      expect(handler).toHaveBeenCalledOnce();
+      const msg = handler.mock.calls[0][0];
+      expect(msg.content.action).toBe('join');
+    });
+  });
+
+  describe('gossip round', () => {
+    it('should perform gossip round', async () => {
+      protocol.start(); // Must be running
+      protocol.addPeer('peer-1', 'addr1');
+      protocol.addPeer('peer-2', 'addr2');
+
+      protocol.publish({ data: 'test' });
+
+      await protocol.gossipRound();
+
+      const stats = protocol.getStats();
+      expect(stats.gossipRounds).toBe(1);
+    });
+
+    it('should not gossip when stopped', async () => {
+      protocol.publish({ data: 'test' });
+
+      await protocol.gossipRound();
+
+      // Gossip round should be skipped
+      expect(protocol.isRunning()).toBe(false);
+    });
+  });
+
+  describe('peer selector', () => {
+    it('should use custom peer selector', () => {
+      const customSelector = vi.fn().mockImplementation((peers) => [peers[0]]);
+      protocol.setPeerSelector(customSelector);
+
+      protocol.addPeer('peer-1', 'addr1');
+      protocol.addPeer('peer-2', 'addr2');
+      protocol.start();
+      protocol.publish({ data: 'x' });
+
+      // Will be called on gossip round
+      protocol.gossipRound();
+
+      expect(customSelector).toHaveBeenCalled();
+    });
+  });
+
+  describe('statistics', () => {
+    it('should return stats', () => {
+      protocol.addPeer('peer-1', 'addr');
+
+      const stats = protocol.getStats();
+
+      expect(stats.peerCount).toBe(1);
+      expect(stats.messagesSent).toBe(0);
+    });
+
+    it('should reset stats', () => {
+      protocol.publish({ data: 'x' });
+      protocol.resetStats();
+
+      const stats = protocol.getStats();
+      expect(stats.messagesSent).toBe(0);
+    });
+  });
+
+  describe('configuration', () => {
+    it('should return config', () => {
+      const config = protocol.getConfig();
+
+      expect(config.fanout).toBeDefined();
+      expect(config.maxTTL).toBeDefined();
+    });
+  });
+});
+
+describe('AntiEntropySync', () => {
+  let protocol: GossipProtocol;
+  let sync: AntiEntropySync;
+
+  beforeEach(() => {
+    protocol = new GossipProtocol('node-sync');
+    sync = new AntiEntropySync('node-sync', protocol);
+  });
+
+  afterEach(() => {
+    protocol.stop();
+  });
+
+  describe('set and get', () => {
+    it('should set and get a value', () => {
+      sync.set('key1', { value: 42 });
+
+      const result = sync.get('key1');
+
+      expect(result).toEqual({ value: 42 });
+    });
+
+    it('should return undefined for unknown keys', () => {
+      expect(sync.get('unknown')).toBeUndefined();
+    });
+
+    it('should list all keys', () => {
+      sync.set('a', 1);
+      sync.set('b', 2);
+
+      const keys = sync.keys();
+
+      expect(keys).toContain('a');
+      expect(keys).toContain('b');
+    });
+  });
+
+  describe('gossip sync', () => {
+    it('should publish on set', async () => {
+      const handler = vi.fn();
+      protocol.subscribe('data', handler);
+
+      sync.set('key1', 'value');
+
+      // Wait for async handlers to complete
+      await new Promise((r) => setTimeout(r, 10));
+
+      // GossipProtocol.publish calls emitToHandlers which calls handler(message, from)
+      expect(handler).toHaveBeenCalledOnce();
+      const msg = handler.mock.calls[0][0];
+      expect(msg.content.key).toBe('key1');
+      expect(msg.content.value).toBe('value');
+    });
+  });
+
+  describe('snapshot', () => {
+    it('should get snapshot of all data', () => {
+      sync.set('x', 1);
+      sync.set('y', 2);
+
+      const snapshot = sync.getSnapshot();
+
+      expect(snapshot.get('x')).toBe(1);
+      expect(snapshot.get('y')).toBe(2);
+    });
+  });
+});

package/src/swarm/messaging/__tests__/SwarmEventBus.prod.test.ts

@@ -0,0 +1,191 @@
+/**
+ * SwarmEventBus — Production Tests
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { SwarmEventBus } from '../SwarmEventBus';
+
+function make(cfg = {}) {
+  return new SwarmEventBus(cfg);
+}
+
+describe('SwarmEventBus — construction', () => {
+  it('constructs without args', () => expect(() => make()).not.toThrow());
+  it('default maxQueueSize=10000', () => expect(make().getConfig().maxQueueSize).toBe(10000));
+  it('default asyncProcessing=true', () => expect(make().getConfig().asyncProcessing).toBe(true));
+  it('initial stats all zero', () => {
+    const s = make().getStats();
+    expect(s.eventsPublished).toBe(0);
+    expect(s.eventsDelivered).toBe(0);
+  });
+});
+
+describe('SwarmEventBus — publish', () => {
+  it('returns event id string', () => {
+    const bus = make();
+    const id = bus.publish('test', 'src', {});
+    expect(typeof id).toBe('string');
+    expect(id.startsWith('evt-')).toBe(true);
+  });
+  it('increments eventsPublished', () => {
+    const bus = make();
+    bus.publish('test', 'src', {});
+    expect(bus.getStats().eventsPublished).toBe(1);
+  });
+  it('drops to dead letter when queue full', () => {
+    const bus = make({ maxQueueSize: 1, asyncProcessing: false });
+    bus.publish('a', 'src', {}); // fills queue
+    bus.publish('b', 'src', {}); // dropped to dead letter
+    expect(bus.getDeadLetterQueue()).toHaveLength(1);
+    expect(bus.getStats().eventsDropped).toBe(1);
+  });
+  it('priority ordering: critical before normal', () => {
+    const bus = make({ asyncProcessing: false });
+    bus.publish('normal', 'src', {}, { priority: 'normal' });
+    bus.publish('critical', 'src', {}, { priority: 'critical' });
+    const pending = bus.getPendingEvents();
+    expect(pending[0].priority).toBe('critical');
+  });
+});
+
+describe('SwarmEventBus — subscribe / unsubscribe', () => {
+  it('subscribe returns subscription id', () => {
+    const bus = make();
+    const id = bus.subscribe('test', () => {});
+    expect(id.startsWith('sub-')).toBe(true);
+  });
+  it('unsubscribe removes subscription', () => {
+    const bus = make();
+    const id = bus.subscribe('test', () => {});
+    expect(bus.unsubscribe(id)).toBe(true);
+    expect(bus.getStats().subscriptions).toBe(0);
+  });
+  it('unsubscribe unknown returns false', () => {
+    expect(make().unsubscribe('ghost')).toBe(false);
+  });
+  it('clearSubscriptions removes all', () => {
+    const bus = make();
+    bus.subscribe('a', () => {});
+    bus.subscribe('b', () => {});
+    bus.clearSubscriptions();
+    expect(bus.getStats().subscriptions).toBe(0);
+  });
+  it('once subscription auto-removed after delivery', async () => {
+    const bus = make({ asyncProcessing: false });
+    bus.once('test', () => {});
+    bus.publish('test', 'src', {});
+    await bus.processQueue();
+    expect(bus.getStats().subscriptions).toBe(0);
+  });
+});
+
+describe('SwarmEventBus — emit (synchronous)', () => {
+  it('delivers synchronously to matching subscriber', () => {
+    let received: unknown[] = [];
+    const bus = make();
+    bus.subscribe('evt.ping', (e) => { received.push(e.payload); });
+    bus.emit('evt.ping', 'src', { val: 42 });
+    expect(received).toHaveLength(1);
+    expect((received[0] as any).val).toBe(42);
+  });
+  it('does not deliver to non-matching subscriber', () => {
+    let received: unknown[] = [];
+    const bus = make();
+    bus.subscribe('other', (e) => { received.push(e.payload); });
+    bus.emit('evt.ping', 'src', {});
+    expect(received).toHaveLength(0);
+  });
+  it('wildcard pattern matches', () => {
+    let received: unknown[] = [];
+    const bus = make();
+    bus.subscribe('swarm.*', (e) => { received.push(e.payload); });
+    bus.emit('swarm.joined', 'src', {});
+    bus.emit('swarm.left', 'src', {});
+    expect(received).toHaveLength(2);
+  });
+  it('regex pattern matches', () => {
+    let received: unknown[] = [];
+    const bus = make();
+    bus.subscribe(/^agent\./, (e) => { received.push(e.payload); });
+    bus.emit('agent.spawn', 'src', {});
+    bus.emit('agent.destroy', 'src', {});
+    bus.emit('other.event', 'src', {});
+    expect(received).toHaveLength(2);
+  });
+  it('exact match only', () => {
+    let received: unknown[] = [];
+    const bus = make();
+    bus.subscribe('exact', (e) => { received.push(e.payload); });
+    bus.emit('exact.extended', 'src', {});
+    expect(received).toHaveLength(0);
+  });
+});
+
+describe('SwarmEventBus — processQueue', () => {
+  it('delivers events to subscribers', async () => {
+    let received: unknown[] = [];
+    const bus = make({ asyncProcessing: false });
+    bus.subscribe('greet', (e) => { received.push(e.payload); });
+    bus.publish('greet', 'src', 'hello');
+    await bus.processQueue();
+    expect(received).toHaveLength(1);
+  });
+  it('skips expired TTL events', async () => {
+    let received: unknown[] = [];
+    const bus = make({ asyncProcessing: false, defaultTTL: 1 });
+    bus.subscribe('late', (e) => { received.push(e.payload); });
+    bus.publish('late', 'src', {}, { ttl: 1 });
+    await new Promise((r) => setTimeout(r, 5)); // let TTL expire
+    await bus.processQueue();
+    expect(received).toHaveLength(0);
+    expect(bus.getStats().eventsDropped).toBeGreaterThan(0);
+  });
+  it('increments eventsDelivered', async () => {
+    const bus = make({ asyncProcessing: false });
+    bus.subscribe('x', () => {});
+    bus.publish('x', 'src', {});
+    await bus.processQueue();
+    expect(bus.getStats().eventsDelivered).toBe(1);
+  });
+  it('unmatched event goes to dead letter', async () => {
+    const bus = make({ asyncProcessing: false, enableDeadLetter: true });
+    bus.publish('unmatched', 'src', {});
+    await bus.processQueue();
+    expect(bus.getDeadLetterQueue()).toHaveLength(1);
+  });
+});
+
+describe('SwarmEventBus — dead letter / replay', () => {
+  it('clearDeadLetterQueue returns and empties', async () => {
+    const bus = make({ asyncProcessing: false });
+    bus.publish('x', 'src', {});
+    await bus.processQueue(); // unmatched → DLQ
+    const dead = bus.clearDeadLetterQueue();
+    expect(dead).toHaveLength(1);
+    expect(bus.getDeadLetterQueue()).toHaveLength(0);
+  });
+  it('replayDeadLetters re-enqueues and delivers', async () => {
+    let received: unknown[] = [];
+    const bus = make({ asyncProcessing: false });
+    bus.publish('retry', 'src', 'payload');
+    await bus.processQueue(); // to DLQ
+    bus.subscribe('retry', (e) => { received.push(e.payload); });
+    bus.replayDeadLetters();
+    await bus.processQueue();
+    expect(received).toContain('payload');
+  });
+});
+
+describe('SwarmEventBus — stats / resetStats / setConfig', () => {
+  it('resetStats zeroes published/delivered/dropped', () => {
+    const bus = make({ asyncProcessing: false });
+    bus.publish('x', 'src', {});
+    bus.resetStats();
+    expect(bus.getStats().eventsPublished).toBe(0);
+    expect(bus.getStats().eventsDelivered).toBe(0);
+  });
+  it('setConfig partial update', () => {
+    const bus = make({ maxQueueSize: 100 });
+    bus.setConfig({ maxQueueSize: 500 });
+    expect(bus.getConfig().maxQueueSize).toBe(500);
+  });
+});