feat: binary-heap event queue with stable tie-breaking

tests/events.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { EventQueue } from '../src/sim/events.js';
+
+describe('EventQueue', () => {
+  it('pops events in time order regardless of insertion order', () => {
+    const q = new EventQueue();
+    q.push(5, 'c', {});
+    q.push(1, 'a', {});
+    q.push(3, 'b', {});
+    expect(q.pop().type).toBe('a');
+    expect(q.pop().type).toBe('b');
+    expect(q.pop().type).toBe('c');
+    expect(q.pop()).toBeNull();
+  });
+
+  it('breaks time ties by insertion order', () => {
+    const q = new EventQueue();
+    q.push(2, 'first', {});
+    q.push(2, 'second', {});
+    expect(q.pop().type).toBe('first');
+    expect(q.pop().type).toBe('second');
+  });
+
+  it('peek does not remove; size tracks contents', () => {
+    const q = new EventQueue();
+    q.push(1, 'a', { n: 7 });
+    expect(q.size).toBe(1);
+    expect(q.peek().time).toBe(1);
+    expect(q.size).toBe(1);
+    expect(q.pop().data.n).toBe(7);
+    expect(q.size).toBe(0);
+    expect(q.peek()).toBeNull();
+  });
+
+  it('survives a large randomized load in order', () => {
+    const q = new EventQueue();
+    const times = Array.from({ length: 500 }, (_, i) => (i * 7919) % 1000);
+    for (const t of times) q.push(t, 'e', {});
+    let last = -1;
+    while (q.size > 0) {
+      const e = q.pop();
+      expect(e.time).toBeGreaterThanOrEqual(last);
+      last = e.time;
+    }
+  });
+});