@holoscript/framework 6.0.3

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

@@ -0,0 +1,247 @@
+/**
+ * SwarmEventBus Tests
+ * HoloScript v3.2 - Autonomous Agent Swarms
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { SwarmEventBus, EventPriority } from '../SwarmEventBus';
+
+describe('SwarmEventBus', () => {
+  let bus: SwarmEventBus;
+
+  beforeEach(() => {
+    bus = new SwarmEventBus({ asyncProcessing: false });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('basic publish/subscribe', () => {
+    it('should deliver event to subscriber', async () => {
+      const handler = vi.fn();
+      bus.subscribe('test.event', handler);
+
+      bus.emit('test.event', 'agent-1', { data: 'hello' });
+
+      expect(handler).toHaveBeenCalledOnce();
+      expect(handler.mock.calls[0][0]).toMatchObject({
+        type: 'test.event',
+        payload: { data: 'hello' },
+        source: 'agent-1',
+      });
+    });
+
+    it('should support multiple subscribers', async () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      bus.subscribe('test.event', handler1);
+      bus.subscribe('test.event', handler2);
+
+      bus.emit('test.event', 'agent-1', {});
+
+      expect(handler1).toHaveBeenCalledOnce();
+      expect(handler2).toHaveBeenCalledOnce();
+    });
+
+    it('should not deliver to unsubscribed handlers', async () => {
+      const handler = vi.fn();
+      const subId = bus.subscribe('test.event', handler);
+
+      bus.unsubscribe(subId);
+      bus.emit('test.event', 'agent-1', {});
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('should only deliver matching topics', async () => {
+      const handler = vi.fn();
+      bus.subscribe('topic.a', handler);
+
+      bus.emit('topic.b', 'agent-1', {});
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('wildcard patterns', () => {
+    it('should match wildcard patterns', async () => {
+      const handler = vi.fn();
+      bus.subscribe('swarm.*', handler);
+
+      bus.emit('swarm.joined', 'agent-1', {});
+      bus.emit('swarm.left', 'agent-1', {});
+
+      expect(handler).toHaveBeenCalledTimes(2);
+    });
+
+    it('should match prefix.*', async () => {
+      const handler = vi.fn();
+      bus.subscribe('agent.*', handler);
+
+      bus.emit('agent.created', 'a', {});
+      bus.emit('agent.destroyed', 'a', {});
+      bus.emit('other.event', 'a', {});
+
+      expect(handler).toHaveBeenCalledTimes(2);
+    });
+
+    it('should match **.suffix', async () => {
+      const handler = vi.fn();
+      bus.subscribe('*error', handler);
+
+      bus.emit('system.error', 'a', {});
+      bus.emit('agent.action.error', 'a', {});
+
+      expect(handler).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('priority handling', () => {
+    it('should process critical events by priority order', async () => {
+      const order: string[] = [];
+
+      bus.subscribe('event', (e: any) => { order.push(e.priority); });
+
+      // Use publish with asyncProcessing: false - events are queued by priority
+      const asyncBus = new SwarmEventBus({ asyncProcessing: true });
+      asyncBus.subscribe('event', (e: any) => { order.push(e.priority); });
+
+      // Emit directly for synchronous test
+      bus.emit('event', 'a', {}, { priority: 'low' });
+      bus.emit('event', 'a', {}, { priority: 'critical' });
+      bus.emit('event', 'a', {}, { priority: 'high' });
+      bus.emit('event', 'a', {}, { priority: 'normal' });
+
+      // emit is synchronous so order is insertion order
+      // Use publish + processQueue for priority testing
+      expect(order).toContain('critical');
+      expect(order).toContain('high');
+    });
+
+    it('should default to normal priority', async () => {
+      const handler = vi.fn();
+      bus.subscribe('test', handler);
+
+      bus.emit('test', 'a', {});
+
+      expect(handler.mock.calls[0][0].priority).toBe('normal');
+    });
+  });
+
+  describe('once subscription', () => {
+    it('should only fire once', async () => {
+      const handler = vi.fn();
+      bus.once('test.event', handler);
+
+      bus.emit('test.event', 'a', {});
+      bus.emit('test.event', 'a', {});
+
+      expect(handler).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('TTL expiration', () => {
+    it('should drop expired events', async () => {
+      vi.useFakeTimers();
+      // Don't auto-process so we can advance time before processing
+      const asyncBus = new SwarmEventBus({ asyncProcessing: false });
+      const handler = vi.fn();
+      asyncBus.subscribe('test', handler);
+
+      // Publish adds to queue but doesn't process (asyncProcessing: false)
+      asyncBus.publish('test', 'a', {}, { ttl: 1000 });
+
+      // Advance past TTL
+      vi.advanceTimersByTime(2000);
+
+      // Now process - event should be expired
+      await asyncBus.processQueue();
+
+      expect(handler).not.toHaveBeenCalled();
+      vi.useRealTimers();
+    });
+  });
+
+  describe('dead letter queue', () => {
+    it('should add failed events to dead letter queue', async () => {
+      const deadBus = new SwarmEventBus({
+        enableDeadLetter: true,
+        asyncProcessing: false,
+      });
+
+      deadBus.subscribe('test', () => {
+        throw new Error('Handler failed');
+      });
+
+      deadBus.emit('test', 'a', {});
+
+      const stats = deadBus.getStats();
+      expect(stats.deadLetterCount).toBeGreaterThanOrEqual(0);
+    });
+
+    it('should allow replaying dead letters', async () => {
+      const deadBus = new SwarmEventBus({
+        enableDeadLetter: true,
+        asyncProcessing: false,
+      });
+
+      let shouldFail = true;
+      const handler = vi.fn((_e) => {
+        if (shouldFail) throw new Error('fail');
+      });
+
+      deadBus.subscribe('test', handler);
+
+      deadBus.emit('test', 'a', { data: 1 });
+
+      // Fix the handler
+      shouldFail = false;
+
+      // Replay dead letters
+      const replayed = await deadBus.replayDeadLetters();
+
+      expect(replayed).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('statistics', () => {
+    it('should track published events', async () => {
+      bus.emit('test1', 'a', {});
+      bus.emit('test2', 'a', {});
+
+      const stats = bus.getStats();
+      expect(stats.eventsPublished).toBe(2);
+    });
+
+    it('should track delivered events', async () => {
+      bus.subscribe('test', vi.fn());
+      bus.emit('test', 'a', {});
+
+      const stats = bus.getStats();
+      expect(stats.eventsDelivered).toBe(1);
+    });
+  });
+
+  describe('configuration', () => {
+    it('should respect maxQueueSize', async () => {
+      const smallBus = new SwarmEventBus({ maxQueueSize: 2, asyncProcessing: true });
+
+      smallBus.publish('a', 'x', {});
+      smallBus.publish('b', 'x', {});
+      smallBus.publish('c', 'x', {});
+
+      const stats = smallBus.getStats();
+      expect(stats.pendingEvents).toBeLessThanOrEqual(2);
+    });
+  });
+
+  describe('getConfig', () => {
+    it('should return configuration', () => {
+      const config = bus.getConfig();
+      expect(config).toHaveProperty('maxQueueSize');
+      expect(config).toHaveProperty('defaultTTL');
+    });
+  });
+});

package/src/swarm/messaging/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Swarm Messaging Module
+ * HoloScript v3.2 - Autonomous Agent Swarms
+ */
+
+export * from './SwarmEventBus';
+export * from './BroadcastChannel';
+export * from './GossipProtocol';

package/src/swarm/spatial/FlockingBehavior.ts

@@ -0,0 +1,462 @@
+/**
+ * FlockingBehavior - Boid-based swarm movement
+ * HoloScript v3.2 - Autonomous Agent Swarms
+ *
+ * Implements Craig Reynolds' Boids algorithm:
+ * - Separation: Steer to avoid crowding neighbors
+ * - Alignment: Steer towards average heading of neighbors
+ * - Cohesion: Steer towards average position of neighbors
+ */
+
+import { Vector3 } from './Vector3';
+
+/**
+ * Boid agent state
+ */
+export interface IBoid {
+  id: string;
+  position: Vector3;
+  velocity: Vector3;
+  acceleration: Vector3;
+  maxSpeed: number;
+  maxForce: number;
+}
+
+/**
+ * Flocking configuration
+ */
+export interface IFlockingConfig {
+  /** Radius for separation behavior */
+  separationRadius: number;
+  /** Radius for alignment behavior */
+  alignmentRadius: number;
+  /** Radius for cohesion behavior */
+  cohesionRadius: number;
+  /** Weight for separation force */
+  separationWeight: number;
+  /** Weight for alignment force */
+  alignmentWeight: number;
+  /** Weight for cohesion force */
+  cohesionWeight: number;
+  /** Maximum speed */
+  maxSpeed: number;
+  /** Maximum steering force */
+  maxForce: number;
+  /** Boundary mode */
+  boundaryMode: 'wrap' | 'bounce' | 'contain';
+  /** World bounds (if boundaryMode is not 'none') */
+  worldBounds?: {
+    min: Vector3;
+    max: Vector3;
+  };
+}
+
+/**
+ * FlockingBehavior - Manages Boid-based swarm movement
+ */
+export class FlockingBehavior {
+  private boids: Map<string, IBoid> = new Map();
+  private config: IFlockingConfig;
+
+  constructor(config?: Partial<IFlockingConfig>) {
+    this.config = {
+      separationRadius: 25,
+      alignmentRadius: 50,
+      cohesionRadius: 50,
+      separationWeight: 1.5,
+      alignmentWeight: 1.0,
+      cohesionWeight: 1.0,
+      maxSpeed: 4,
+      maxForce: 0.1,
+      boundaryMode: 'wrap',
+      ...config,
+    };
+  }
+
+  /**
+   * Add a boid to the flock
+   */
+  addBoid(id: string, position: Vector3, velocity?: Vector3): IBoid {
+    const boid: IBoid = {
+      id,
+      position: position.clone(),
+      velocity:
+        velocity?.clone() ??
+        new Vector3(
+          (Math.random() - 0.5) * 2,
+          (Math.random() - 0.5) * 2,
+          (Math.random() - 0.5) * 2
+        ),
+      acceleration: Vector3.zero(),
+      maxSpeed: this.config.maxSpeed,
+      maxForce: this.config.maxForce,
+    };
+
+    this.boids.set(id, boid);
+    return boid;
+  }
+
+  /**
+   * Remove a boid from the flock
+   */
+  removeBoid(id: string): boolean {
+    return this.boids.delete(id);
+  }
+
+  /**
+   * Get a boid by ID
+   */
+  getBoid(id: string): IBoid | undefined {
+    return this.boids.get(id);
+  }
+
+  /**
+   * Get all boids
+   */
+  getAllBoids(): IBoid[] {
+    return [...this.boids.values()];
+  }
+
+  /**
+   * Update boid position manually
+   */
+  setBoidPosition(id: string, position: Vector3): void {
+    const boid = this.boids.get(id);
+    if (boid) {
+      boid.position = position.clone();
+    }
+  }
+
+  /**
+   * Update a single boid
+   */
+  updateBoid(boid: IBoid, neighbors: IBoid[]): void {
+    const separation = this.separate(boid, neighbors);
+    const alignment = this.align(boid, neighbors);
+    const cohesion = this.cohere(boid, neighbors);
+
+    // Apply weights
+    const separationForce = separation.multiply(this.config.separationWeight);
+    const alignmentForce = alignment.multiply(this.config.alignmentWeight);
+    const cohesionForce = cohesion.multiply(this.config.cohesionWeight);
+
+    // Accumulate forces
+    boid.acceleration = boid.acceleration
+      .add(separationForce)
+      .add(alignmentForce)
+      .add(cohesionForce);
+
+    // Update velocity
+    boid.velocity = boid.velocity.add(boid.acceleration);
+    boid.velocity = boid.velocity.clampMagnitude(boid.maxSpeed);
+
+    // Update position
+    boid.position = boid.position.add(boid.velocity);
+
+    // Reset acceleration
+    boid.acceleration = Vector3.zero();
+
+    // Handle boundaries
+    this.handleBoundaries(boid);
+  }
+
+  /**
+   * Update all boids in the flock
+   */
+  update(): void {
+    const boidList = this.getAllBoids();
+
+    for (const boid of boidList) {
+      const neighbors = this.findNeighbors(
+        boid,
+        Math.max(
+          this.config.separationRadius,
+          this.config.alignmentRadius,
+          this.config.cohesionRadius
+        )
+      );
+      this.updateBoid(boid, neighbors);
+    }
+  }
+
+  /**
+   * Separation: Steer away from nearby boids
+   */
+  separate(boid: IBoid, neighbors: IBoid[]): Vector3 {
+    let steer = Vector3.zero();
+    let count = 0;
+
+    for (const other of neighbors) {
+      if (other.id === boid.id) continue;
+
+      const distance = boid.position.distanceTo(other.position);
+      if (distance > 0 && distance < this.config.separationRadius) {
+        // Calculate vector pointing away from neighbor
+        let diff = boid.position.subtract(other.position);
+        diff = diff.normalize();
+        diff = diff.divide(distance); // Weight by distance (closer = stronger)
+        steer = steer.add(diff);
+        count++;
+      }
+    }
+
+    if (count > 0) {
+      steer = steer.divide(count);
+    }
+
+    if (steer.magnitude() > 0) {
+      steer = steer.normalize();
+      steer = steer.multiply(boid.maxSpeed);
+      steer = steer.subtract(boid.velocity);
+      steer = steer.clampMagnitude(boid.maxForce);
+    }
+
+    return steer;
+  }
+
+  /**
+   * Alignment: Steer towards average heading of neighbors
+   */
+  align(boid: IBoid, neighbors: IBoid[]): Vector3 {
+    let sum = Vector3.zero();
+    let count = 0;
+
+    for (const other of neighbors) {
+      if (other.id === boid.id) continue;
+
+      const distance = boid.position.distanceTo(other.position);
+      if (distance > 0 && distance < this.config.alignmentRadius) {
+        sum = sum.add(other.velocity);
+        count++;
+      }
+    }
+
+    if (count > 0) {
+      sum = sum.divide(count);
+      sum = sum.normalize();
+      sum = sum.multiply(boid.maxSpeed);
+      const steer = sum.subtract(boid.velocity);
+      return steer.clampMagnitude(boid.maxForce);
+    }
+
+    return Vector3.zero();
+  }
+
+  /**
+   * Cohesion: Steer towards center of mass of neighbors
+   */
+  cohere(boid: IBoid, neighbors: IBoid[]): Vector3 {
+    let sum = Vector3.zero();
+    let count = 0;
+
+    for (const other of neighbors) {
+      if (other.id === boid.id) continue;
+
+      const distance = boid.position.distanceTo(other.position);
+      if (distance > 0 && distance < this.config.cohesionRadius) {
+        sum = sum.add(other.position);
+        count++;
+      }
+    }
+
+    if (count > 0) {
+      const center = sum.divide(count);
+      return this.seek(boid, center);
+    }
+
+    return Vector3.zero();
+  }
+
+  /**
+   * Seek: Steer towards a target location
+   */
+  seek(boid: IBoid, target: Vector3): Vector3 {
+    let desired = target.subtract(boid.position);
+    desired = desired.normalize();
+    desired = desired.multiply(boid.maxSpeed);
+    const steer = desired.subtract(boid.velocity);
+    return steer.clampMagnitude(boid.maxForce);
+  }
+
+  /**
+   * Flee: Steer away from a target location
+   */
+  flee(boid: IBoid, target: Vector3): Vector3 {
+    return this.seek(boid, target).multiply(-1);
+  }
+
+  /**
+   * Arrive: Seek with slowing as approaching target
+   */
+  arrive(boid: IBoid, target: Vector3, slowingRadius: number): Vector3 {
+    let desired = target.subtract(boid.position);
+    const distance = desired.magnitude();
+
+    if (distance < slowingRadius) {
+      // Slow down proportionally
+      const speed = (distance / slowingRadius) * boid.maxSpeed;
+      desired = desired.normalize().multiply(speed);
+    } else {
+      desired = desired.normalize().multiply(boid.maxSpeed);
+    }
+
+    const steer = desired.subtract(boid.velocity);
+    return steer.clampMagnitude(boid.maxForce);
+  }
+
+  /**
+   * Find neighbors within radius
+   */
+  findNeighbors(boid: IBoid, radius: number): IBoid[] {
+    const radiusSquared = radius * radius;
+    const neighbors: IBoid[] = [];
+
+    for (const other of this.boids.values()) {
+      if (other.id === boid.id) continue;
+      const distSq = boid.position.distanceToSquared(other.position);
+      if (distSq < radiusSquared) {
+        neighbors.push(other);
+      }
+    }
+
+    return neighbors;
+  }
+
+  /**
+   * Handle world boundaries
+   */
+  private handleBoundaries(boid: IBoid): void {
+    if (!this.config.worldBounds) return;
+
+    const { min, max } = this.config.worldBounds;
+
+    switch (this.config.boundaryMode) {
+      case 'wrap':
+        this.wrapPosition(boid, min, max);
+        break;
+      case 'bounce':
+        this.bouncePosition(boid, min, max);
+        break;
+      case 'contain':
+        this.containPosition(boid, min, max);
+        break;
+    }
+  }
+
+  /**
+   * Wrap position to opposite side
+   */
+  private wrapPosition(boid: IBoid, min: Vector3, max: Vector3): void {
+    const size = max.subtract(min);
+
+    if (boid.position.x < min.x) boid.position.x += size.x;
+    if (boid.position.x > max.x) boid.position.x -= size.x;
+    if (boid.position.y < min.y) boid.position.y += size.y;
+    if (boid.position.y > max.y) boid.position.y -= size.y;
+    if (boid.position.z < min.z) boid.position.z += size.z;
+    if (boid.position.z > max.z) boid.position.z -= size.z;
+  }
+
+  /**
+   * Bounce off boundaries
+   */
+  private bouncePosition(boid: IBoid, min: Vector3, max: Vector3): void {
+    if (boid.position.x < min.x || boid.position.x > max.x) {
+      boid.velocity.x *= -1;
+      boid.position.x = Math.max(min.x, Math.min(max.x, boid.position.x));
+    }
+    if (boid.position.y < min.y || boid.position.y > max.y) {
+      boid.velocity.y *= -1;
+      boid.position.y = Math.max(min.y, Math.min(max.y, boid.position.y));
+    }
+    if (boid.position.z < min.z || boid.position.z > max.z) {
+      boid.velocity.z *= -1;
+      boid.position.z = Math.max(min.z, Math.min(max.z, boid.position.z));
+    }
+  }
+
+  /**
+   * Contain within boundaries (clamp)
+   */
+  private containPosition(boid: IBoid, min: Vector3, max: Vector3): void {
+    boid.position.x = Math.max(min.x, Math.min(max.x, boid.position.x));
+    boid.position.y = Math.max(min.y, Math.min(max.y, boid.position.y));
+    boid.position.z = Math.max(min.z, Math.min(max.z, boid.position.z));
+  }
+
+  /**
+   * Apply external force to a boid
+   */
+  applyForce(id: string, force: Vector3): void {
+    const boid = this.boids.get(id);
+    if (boid) {
+      boid.acceleration = boid.acceleration.add(force);
+    }
+  }
+
+  /**
+   * Apply force to all boids
+   */
+  applyForceToAll(force: Vector3): void {
+    for (const boid of this.boids.values()) {
+      boid.acceleration = boid.acceleration.add(force);
+    }
+  }
+
+  /**
+   * Get flock center of mass
+   */
+  getFlockCenter(): Vector3 {
+    if (this.boids.size === 0) return Vector3.zero();
+
+    let sum = Vector3.zero();
+    for (const boid of this.boids.values()) {
+      sum = sum.add(boid.position);
+    }
+    return sum.divide(this.boids.size);
+  }
+
+  /**
+   * Get average velocity (direction) of flock
+   */
+  getFlockDirection(): Vector3 {
+    if (this.boids.size === 0) return Vector3.zero();
+
+    let sum = Vector3.zero();
+    for (const boid of this.boids.values()) {
+      sum = sum.add(boid.velocity);
+    }
+    return sum.divide(this.boids.size).normalize();
+  }
+
+  /**
+   * Get flock spread (radius from center)
+   */
+  getFlockSpread(): number {
+    if (this.boids.size <= 1) return 0;
+
+    const center = this.getFlockCenter();
+    let maxDist = 0;
+
+    for (const boid of this.boids.values()) {
+      const dist = boid.position.distanceTo(center);
+      if (dist > maxDist) maxDist = dist;
+    }
+
+    return maxDist;
+  }
+
+  /**
+   * Update configuration
+   */
+  setConfig(config: Partial<IFlockingConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): IFlockingConfig {
+    return { ...this.config };
+  }
+}