@holoscript/framework 6.0.3

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

@@ -0,0 +1,331 @@
+/**
+ * BroadcastChannel + ChannelManager — Production Tests
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { BroadcastChannel, ChannelManager } from '../BroadcastChannel';
+
+function makeCh(cfg = {}) {
+  return new BroadcastChannel('ch1', 'TestChannel', cfg);
+}
+function makeMgr() {
+  return new ChannelManager();
+}
+
+// ─── BroadcastChannel ───────────────────────────────────
+
+describe('BroadcastChannel — construction', () => {
+  it('id and name stored', () => {
+    const c = makeCh();
+    expect(c.id).toBe('ch1');
+    expect(c.name).toBe('TestChannel');
+  });
+  it('createdAt is recent', () => {
+    expect(Date.now() - makeCh().createdAt).toBeLessThan(100);
+  });
+  it('default maxSubscribers=1000', () => {
+    expect(makeCh().getConfig().maxSubscribers).toBe(1000);
+  });
+  it('default historySize=100', () => {
+    expect(makeCh().getConfig().historySize).toBe(100);
+  });
+  it('default allowReplay=true', () => {
+    expect(makeCh().getConfig().allowReplay).toBe(true);
+  });
+});
+
+describe('BroadcastChannel — subscribe / unsubscribe', () => {
+  it('subscribe returns subId', () => {
+    const c = makeCh();
+    const id = c.subscribe('a1', () => {});
+    expect(id.startsWith('sub-a1')).toBe(true);
+  });
+  it('isSubscribed=true after subscribe', () => {
+    const c = makeCh();
+    c.subscribe('a1', () => {});
+    expect(c.isSubscribed('a1')).toBe(true);
+  });
+  it('isSubscribed=false for unknown', () => {
+    expect(makeCh().isSubscribed('ghost')).toBe(false);
+  });
+  it('getSubscriberCount increments', () => {
+    const c = makeCh();
+    c.subscribe('a1', () => {});
+    c.subscribe('a2', () => {});
+    expect(c.getSubscriberCount()).toBe(2);
+  });
+  it('unsubscribe returns true', () => {
+    const c = makeCh();
+    const id = c.subscribe('a1', () => {});
+    expect(c.unsubscribe(id)).toBe(true);
+  });
+  it('unsubscribe decrements count', () => {
+    const c = makeCh();
+    const id = c.subscribe('a1', () => {});
+    c.unsubscribe(id);
+    expect(c.getSubscriberCount()).toBe(0);
+  });
+  it('unsubscribe unknown returns false', () => {
+    expect(makeCh().unsubscribe('ghost')).toBe(false);
+  });
+  it('throws when maxSubscribers reached', () => {
+    const c = makeCh({ maxSubscribers: 1 });
+    c.subscribe('a1', () => {});
+    expect(() => c.subscribe('a2', () => {})).toThrow();
+  });
+});
+
+describe('BroadcastChannel — broadcast', () => {
+  it('delivers to subscriber', async () => {
+    const received: unknown[] = [];
+    const c = makeCh();
+    c.subscribe('a1', (m) => { received.push((m as any).content); });
+    await c.broadcast('sender', 'hello');
+    expect(received).toHaveLength(1);
+    expect(received[0]).toBe('hello');
+  });
+  it('delivered to all subscribers', async () => {
+    const received: unknown[] = [];
+    const c = makeCh();
+    c.subscribe('a1', (m) => { received.push(m); });
+    c.subscribe('a2', (m) => { received.push(m); });
+    await c.broadcast('sender', 'hi');
+    expect(received).toHaveLength(2);
+  });
+  it('publisher-role subscriber does not receive', async () => {
+    const received: unknown[] = [];
+    const c = makeCh();
+    c.subscribe('a1', (m) => { received.push('a1', m); }, { role: 'publisher' });
+    await c.broadcast('sender', 'hi');
+    expect(received).toHaveLength(0);
+  });
+  it('returns message id string', async () => {
+    const c = makeCh();
+    const id = await c.broadcast('sender', 'x');
+    expect(id.startsWith('msg-')).toBe(true);
+  });
+  it('adds to history', async () => {
+    const c = makeCh();
+    await c.broadcast('s', 'a');
+    await c.broadcast('s', 'b');
+    expect(c.getStats().historySize).toBe(2);
+  });
+  it('historySize cap enforced', async () => {
+    const c = makeCh({ historySize: 2 });
+    await c.broadcast('s', 'a');
+    await c.broadcast('s', 'b');
+    await c.broadcast('s', 'c');
+    expect(c.getStats().historySize).toBe(2);
+  });
+});
+
+describe('BroadcastChannel — sendDirect', () => {
+  it('delivers only to target', async () => {
+    const received: string[] = [];
+    const c = makeCh();
+    c.subscribe('a1', () => { received.push('a1'); });
+    c.subscribe('a2', () => { received.push('a2'); });
+    await c.sendDirect('sender', 'a1', 'dm');
+    expect(received).toHaveLength(1);
+    expect(received[0]).toBe('a1');
+  });
+  it('returns messageId on delivery', async () => {
+    const c = makeCh();
+    c.subscribe('a1', () => {});
+    const id = await c.sendDirect('s', 'a1', 'hi');
+    expect(id).not.toBeNull();
+  });
+  it('returns null for unknown target', async () => {
+    const c = makeCh();
+    expect(await c.sendDirect('s', 'nobody', 'hi')).toBeNull();
+  });
+});
+
+describe('BroadcastChannel — ACK', () => {
+  it('requireAck tracks pending', async () => {
+    const c = makeCh({ requireAck: true });
+    c.subscribe('a1', () => {});
+    c.subscribe('a2', () => {});
+    const id = await c.broadcast('sender', 'hi');
+    expect(c.getPendingAcks(id)).toHaveLength(2);
+  });
+  it('acknowledge reduces pending', async () => {
+    const c = makeCh({ requireAck: true });
+    c.subscribe('a1', () => {});
+    c.subscribe('a2', () => {});
+    const id = await c.broadcast('sender', 'hi');
+    c.acknowledge(id, 'a1');
+    expect(c.getPendingAcks(id)).toHaveLength(1);
+  });
+  it('isFullyAcknowledged after all ack', async () => {
+    const c = makeCh({ requireAck: true });
+    c.subscribe('a1', () => {});
+    const id = await c.broadcast('sender', 'hi');
+    c.acknowledge(id, 'a1');
+    expect(c.isFullyAcknowledged(id)).toBe(true);
+  });
+  it('acknowledge unknown returns false', () => {
+    expect(makeCh().acknowledge('ghost', 'a1')).toBe(false);
+  });
+  it('isFullyAcknowledged true for no-requireAck', async () => {
+    const c = makeCh({ requireAck: false });
+    c.subscribe('a1', () => {});
+    const id = await c.broadcast('sender', 'hi');
+    expect(c.isFullyAcknowledged(id)).toBe(true);
+  });
+});
+
+describe('BroadcastChannel — getHistory', () => {
+  it('returns empty when allowReplay=false', async () => {
+    const c = makeCh({ allowReplay: false });
+    await c.broadcast('s', 'hi');
+    expect(c.getHistory()).toHaveLength(0);
+  });
+  it('returns messages when allowReplay=true', async () => {
+    const c = makeCh();
+    await c.broadcast('s', 'a');
+    await c.broadcast('s', 'b');
+    expect(c.getHistory()).toHaveLength(2);
+  });
+  it('limit option returns last N', async () => {
+    const c = makeCh();
+    await c.broadcast('s', '1');
+    await c.broadcast('s', '2');
+    await c.broadcast('s', '3');
+    expect(c.getHistory({ limit: 2 })).toHaveLength(2);
+  });
+  it('senderId filter', async () => {
+    const c = makeCh();
+    await c.broadcast('alice', 'hi');
+    await c.broadcast('bob', 'there');
+    expect(c.getHistory({ senderId: 'alice' })).toHaveLength(1);
+  });
+  it('clearHistory empties history', async () => {
+    const c = makeCh();
+    await c.broadcast('s', 'x');
+    c.clearHistory();
+    expect(c.getStats().historySize).toBe(0);
+  });
+});
+
+describe('BroadcastChannel — replayHistory', () => {
+  it('replays all history to subscriber', async () => {
+    const received: unknown[] = [];
+    const c = makeCh();
+    await c.broadcast('s', '1');
+    await c.broadcast('s', '2');
+    const subId = c.subscribe('a1', (m) => { received.push(m); });
+    const count = await c.replayHistory(subId);
+    expect(count).toBe(2);
+    expect(received).toHaveLength(2);
+  });
+  it('replayHistory=0 for unknown subscriber', async () => {
+    const c = makeCh();
+    await c.broadcast('s', 'x');
+    expect(await c.replayHistory('ghost')).toBe(0);
+  });
+  it('replay disabled when allowReplay=false', async () => {
+    const c = makeCh({ allowReplay: false });
+    await c.broadcast('s', 'x');
+    const id = c.subscribe('a1', () => {});
+    expect(await c.replayHistory(id)).toBe(0);
+  });
+});
+
+describe('BroadcastChannel — getStats', () => {
+  it('all fields present', async () => {
+    const c = makeCh();
+    await c.broadcast('s', 'hi');
+    const stats = c.getStats();
+    expect(stats).toHaveProperty('subscriberCount');
+    expect(stats).toHaveProperty('historySize');
+    expect(stats).toHaveProperty('pendingAckCount');
+    expect(stats).toHaveProperty('oldestMessage');
+    expect(stats).toHaveProperty('newestMessage');
+  });
+  it('oldestMessage=null when no history', () => {
+    expect(makeCh().getStats().oldestMessage).toBeNull();
+  });
+});
+
+// ─── ChannelManager ───────────────────────────────────
+
+describe('ChannelManager — createChannel / getChannel', () => {
+  it('createChannel returns BroadcastChannel', () => {
+    const m = makeMgr();
+    const c = m.createChannel('general');
+    expect(c).toBeInstanceOf(BroadcastChannel);
+    expect(c.name).toBe('general');
+  });
+  it('getChannel by id', () => {
+    const m = makeMgr();
+    const c = m.createChannel('news');
+    expect(m.getChannel(c.id)).toBe(c);
+  });
+  it('getChannelByName', () => {
+    const m = makeMgr();
+    const c = m.createChannel('sport');
+    expect(m.getChannelByName('sport')).toBe(c);
+  });
+  it('getChannelByName unknown=undefined', () => {
+    expect(makeMgr().getChannelByName('ghost')).toBeUndefined();
+  });
+  it('getAllChannels returns all', () => {
+    const m = makeMgr();
+    m.createChannel('a');
+    m.createChannel('b');
+    expect(m.getAllChannels()).toHaveLength(2);
+  });
+  it('getChannelCount', () => {
+    const m = makeMgr();
+    m.createChannel('x');
+    m.createChannel('y');
+    expect(m.getChannelCount()).toBe(2);
+  });
+  it('deleteChannel removes channel', () => {
+    const m = makeMgr();
+    const c = m.createChannel('temp');
+    m.deleteChannel(c.id);
+    expect(m.getChannel(c.id)).toBeUndefined();
+  });
+  it('deleteChannel unknown returns false', () => {
+    expect(makeMgr().deleteChannel('ghost')).toBe(false);
+  });
+});
+
+describe('ChannelManager — subscribeAgent', () => {
+  it('subscribeAgent returns subscriberId', () => {
+    const m = makeMgr();
+    const c = m.createChannel('ch');
+    expect(m.subscribeAgent('a1', c.id, () => {})).toBeTruthy();
+  });
+  it('getAgentChannels returns subscribed', () => {
+    const m = makeMgr();
+    const c = m.createChannel('ch');
+    m.subscribeAgent('a1', c.id, () => {});
+    expect(m.getAgentChannels('a1')).toHaveLength(1);
+  });
+  it('subscribeAgent unknown channel throws', () => {
+    const m = makeMgr();
+    expect(() => m.subscribeAgent('a1', 'ghost', () => {})).toThrow();
+  });
+});
+
+describe('ChannelManager — multicast', () => {
+  it('delivers to all target channels', async () => {
+    const m = makeMgr();
+    const c1 = m.createChannel('c1');
+    const c2 = m.createChannel('c2');
+    const received: string[] = [];
+    m.subscribeAgent('a1', c1.id, () => { received.push('c1'); });
+    m.subscribeAgent('a2', c2.id, () => { received.push('c2'); });
+    const results = await m.multicast([c1.id, c2.id], 'sender', 'msg');
+    expect(results.size).toBe(2);
+    expect(received).toHaveLength(2);
+  });
+  it('skips unknown channel ids silently', async () => {
+    const m = makeMgr();
+    const c = m.createChannel('c1');
+    const results = await m.multicast([c.id, 'ghost'], 'sender', 'hi');
+    expect(results.size).toBe(1);
+  });
+});

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

@@ -0,0 +1,333 @@
+/**
+ * BroadcastChannel Tests
+ * HoloScript v3.2 - Autonomous Agent Swarms
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { BroadcastChannel, ChannelManager } from '../BroadcastChannel';
+
+describe('BroadcastChannel', () => {
+  let channel: BroadcastChannel;
+
+  beforeEach(() => {
+    channel = new BroadcastChannel('ch-1', 'test-channel');
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('subscription', () => {
+    it('should subscribe an agent', () => {
+      const handler = vi.fn();
+      const subId = channel.subscribe('agent-1', handler);
+
+      expect(subId).toBeDefined();
+      expect(channel.isSubscribed('agent-1')).toBe(true);
+    });
+
+    it('should unsubscribe an agent', () => {
+      const handler = vi.fn();
+      const subId = channel.subscribe('agent-1', handler);
+
+      const removed = channel.unsubscribe(subId);
+
+      expect(removed).toBe(true);
+      expect(channel.getSubscriberCount()).toBe(0);
+    });
+
+    it('should support role-based subscription', () => {
+      const handler = vi.fn();
+      channel.subscribe('agent-1', handler, { role: 'publisher' });
+      channel.subscribe('agent-2', handler, { role: 'subscriber' });
+
+      const subs = channel.getSubscribers();
+      expect(subs.find((s) => s.agentId === 'agent-1')?.role).toBe('publisher');
+      expect(subs.find((s) => s.agentId === 'agent-2')?.role).toBe('subscriber');
+    });
+
+    it('should enforce maxSubscribers', () => {
+      const smallChannel = new BroadcastChannel('ch-1', 'small', { maxSubscribers: 2 });
+
+      smallChannel.subscribe('a1', vi.fn());
+      smallChannel.subscribe('a2', vi.fn());
+
+      expect(() => smallChannel.subscribe('a3', vi.fn())).toThrow(/maximum subscribers/);
+    });
+  });
+
+  describe('broadcast', () => {
+    it('should deliver to all subscribers', async () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      channel.subscribe('agent-1', handler1);
+      channel.subscribe('agent-2', handler2);
+
+      await channel.broadcast('sender', { data: 'test' });
+
+      expect(handler1).toHaveBeenCalledOnce();
+      expect(handler2).toHaveBeenCalledOnce();
+    });
+
+    it('should not deliver to publisher-only subscribers', async () => {
+      const pubHandler = vi.fn();
+      const subHandler = vi.fn();
+
+      channel.subscribe('publisher', pubHandler, { role: 'publisher' });
+      channel.subscribe('subscriber', subHandler, { role: 'subscriber' });
+
+      await channel.broadcast('sender', { data: 'test' });
+
+      expect(pubHandler).not.toHaveBeenCalled();
+      expect(subHandler).toHaveBeenCalledOnce();
+    });
+
+    it('should return message ID', async () => {
+      channel.subscribe('a1', vi.fn());
+      const msgId = await channel.broadcast('sender', { data: 'test' });
+
+      expect(msgId).toContain('msg-');
+    });
+
+    it('should include metadata', async () => {
+      const handler = vi.fn();
+      channel.subscribe('agent-1', handler);
+
+      await channel.broadcast('sender', { data: 'x' }, { metadata: { priority: 'high' } });
+
+      expect(handler.mock.calls[0][0].metadata).toEqual({ priority: 'high' });
+    });
+  });
+
+  describe('direct messages', () => {
+    it('should send to specific agent', async () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      channel.subscribe('agent-1', handler1);
+      channel.subscribe('agent-2', handler2);
+
+      await channel.sendDirect('sender', 'agent-2', { data: 'private' });
+
+      expect(handler1).not.toHaveBeenCalled();
+      expect(handler2).toHaveBeenCalledOnce();
+    });
+
+    it('should return null if target not found', async () => {
+      channel.subscribe('agent-1', vi.fn());
+
+      const result = await channel.sendDirect('sender', 'unknown', { data: 'x' });
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('acknowledgments', () => {
+    it('should track pending acks', async () => {
+      const ackChannel = new BroadcastChannel('ack-ch', 'ack-test', { requireAck: true });
+
+      ackChannel.subscribe('agent-1', vi.fn());
+      ackChannel.subscribe('agent-2', vi.fn());
+
+      const msgId = await ackChannel.broadcast('sender', { data: 'x' });
+
+      const pending = ackChannel.getPendingAcks(msgId);
+      expect(pending).toContain('agent-1');
+      expect(pending).toContain('agent-2');
+    });
+
+    it('should remove ack when acknowledged', async () => {
+      const ackChannel = new BroadcastChannel('ack-ch', 'ack-test', { requireAck: true });
+
+      ackChannel.subscribe('agent-1', vi.fn());
+
+      const msgId = await ackChannel.broadcast('sender', { data: 'x' });
+      ackChannel.acknowledge(msgId, 'agent-1');
+
+      expect(ackChannel.isFullyAcknowledged(msgId)).toBe(true);
+    });
+  });
+
+  describe('history', () => {
+    it('should maintain message history', async () => {
+      channel.subscribe('a1', vi.fn());
+
+      await channel.broadcast('s', { msg: 1 });
+      await channel.broadcast('s', { msg: 2 });
+
+      const history = channel.getHistory();
+      expect(history.length).toBe(2);
+    });
+
+    it('should limit history size', async () => {
+      const smallHistory = new BroadcastChannel('ch', 'small', { historySize: 2 });
+      smallHistory.subscribe('a1', vi.fn());
+
+      await smallHistory.broadcast('s', { msg: 1 });
+      await smallHistory.broadcast('s', { msg: 2 });
+      await smallHistory.broadcast('s', { msg: 3 });
+
+      const history = smallHistory.getHistory();
+      expect(history.length).toBe(2);
+    });
+
+    it('should filter history by senderId', async () => {
+      channel.subscribe('a1', vi.fn());
+
+      await channel.broadcast('s1', { data: 1 });
+      await channel.broadcast('s2', { data: 2 });
+
+      const history = channel.getHistory({ senderId: 's1' });
+      expect(history.length).toBe(1);
+      expect(history[0].senderId).toBe('s1');
+    });
+
+    it('should replay history to subscriber', async () => {
+      const handler1 = vi.fn();
+      channel.subscribe('a1', handler1);
+
+      await channel.broadcast('s', { msg: 1 });
+      await channel.broadcast('s', { msg: 2 });
+
+      const newHandler = vi.fn();
+      const newSubId = channel.subscribe('a2', newHandler);
+
+      const replayed = await channel.replayHistory(newSubId);
+
+      expect(replayed).toBe(2);
+      expect(newHandler).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not replay when replay disabled', async () => {
+      const noReplay = new BroadcastChannel('ch', 'no-replay', { allowReplay: false });
+      noReplay.subscribe('a1', vi.fn());
+      await noReplay.broadcast('s', { msg: 1 });
+
+      const handler = vi.fn();
+      const subId = noReplay.subscribe('a2', handler);
+
+      const replayed = await noReplay.replayHistory(subId);
+
+      expect(replayed).toBe(0);
+    });
+
+    it('should clear history', async () => {
+      channel.subscribe('a1', vi.fn());
+      await channel.broadcast('s', { msg: 1 });
+
+      channel.clearHistory();
+
+      expect(channel.getHistory().length).toBe(0);
+    });
+  });
+
+  describe('statistics', () => {
+    it('should return stats', async () => {
+      channel.subscribe('a1', vi.fn());
+      await channel.broadcast('s', { msg: 1 });
+
+      const stats = channel.getStats();
+
+      expect(stats.subscriberCount).toBe(1);
+      expect(stats.historySize).toBe(1);
+    });
+  });
+});
+
+describe('ChannelManager', () => {
+  let manager: ChannelManager;
+
+  beforeEach(() => {
+    manager = new ChannelManager();
+  });
+
+  describe('channel management', () => {
+    it('should create a channel', () => {
+      const channel = manager.createChannel('test-channel');
+
+      expect(channel.name).toBe('test-channel');
+      expect(manager.getChannelCount()).toBe(1);
+    });
+
+    it('should get channel by ID', () => {
+      const channel = manager.createChannel('test');
+
+      const found = manager.getChannel(channel.id);
+
+      expect(found).toBe(channel);
+    });
+
+    it('should get channel by name', () => {
+      manager.createChannel('my-channel');
+
+      const found = manager.getChannelByName('my-channel');
+
+      expect(found?.name).toBe('my-channel');
+    });
+
+    it('should delete a channel', () => {
+      const channel = manager.createChannel('test');
+
+      const deleted = manager.deleteChannel(channel.id);
+
+      expect(deleted).toBe(true);
+      expect(manager.getChannelCount()).toBe(0);
+    });
+
+    it('should list all channels', () => {
+      manager.createChannel('ch1');
+      manager.createChannel('ch2');
+
+      const channels = manager.getAllChannels();
+
+      expect(channels.length).toBe(2);
+    });
+  });
+
+  describe('agent subscription', () => {
+    it('should subscribe agent to channel', () => {
+      const channel = manager.createChannel('test');
+
+      const subId = manager.subscribeAgent('agent-1', channel.id, vi.fn());
+
+      expect(subId).toBeDefined();
+      expect(channel.isSubscribed('agent-1')).toBe(true);
+    });
+
+    it('should track agent channels', () => {
+      const ch1 = manager.createChannel('ch1');
+      const ch2 = manager.createChannel('ch2');
+
+      manager.subscribeAgent('agent-1', ch1.id, vi.fn());
+      manager.subscribeAgent('agent-1', ch2.id, vi.fn());
+
+      const agentChannels = manager.getAgentChannels('agent-1');
+
+      expect(agentChannels.length).toBe(2);
+    });
+
+    it('should throw if channel not found', () => {
+      expect(() => manager.subscribeAgent('a', 'unknown', vi.fn())).toThrow(/not found/);
+    });
+  });
+
+  describe('multicast', () => {
+    it('should broadcast to multiple channels', async () => {
+      const ch1 = manager.createChannel('ch1');
+      const ch2 = manager.createChannel('ch2');
+
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      ch1.subscribe('a1', handler1);
+      ch2.subscribe('a2', handler2);
+
+      const results = await manager.multicast([ch1.id, ch2.id], 'sender', { data: 'multi' });
+
+      expect(results.size).toBe(2);
+      expect(handler1).toHaveBeenCalledOnce();
+      expect(handler2).toHaveBeenCalledOnce();
+    });
+  });
+});