@holoscript/framework 6.0.3

package/src/ai/__tests__/NavMesh.prod.test.ts

@@ -0,0 +1,141 @@
+/**
+ * NavMesh — Production Test Suite
+ *
+ * Covers: polygon management, connections, A* pathfinding,
+ * path smoothing, walkability, cost, queries.
+ */
+import { describe, it, expect } from 'vitest';
+import { NavMesh } from '../NavMesh';
+
+function tri(x: number, z: number): { x: number; z: number }[] {
+  return [
+    { x, z },
+    { x: x + 2, z },
+    { x: x + 1, z: z + 2 },
+  ];
+}
+
+describe('NavMesh — Production', () => {
+  // ─── Polygon Management ───────────────────────────────────────────
+  it('addPolygon assigns auto-incrementing id', () => {
+    const nav = new NavMesh();
+    const id0 = nav.addPolygon(tri(0, 0));
+    const id1 = nav.addPolygon(tri(3, 0));
+    expect(id0).toBe(0);
+    expect(id1).toBe(1);
+    expect(nav.getPolygonCount()).toBe(2);
+  });
+
+  it('polygon center is computed correctly', () => {
+    const nav = new NavMesh();
+    const id = nav.addPolygon([
+      { x: 0, z: 0 },
+      { x: 3, z: 0 },
+      { x: 0, z: 3 },
+    ]);
+    const poly = nav.getPolygon(id);
+    expect(poly!.center.x).toBe(1);
+    expect(poly!.center.z).toBe(1);
+  });
+
+  // ─── Connections ──────────────────────────────────────────────────
+  it('connect links two polygons bidirectionally', () => {
+    const nav = new NavMesh();
+    const a = nav.addPolygon(tri(0, 0));
+    const b = nav.addPolygon(tri(3, 0));
+    expect(nav.connect(a, b)).toBe(true);
+    expect(nav.getPolygon(a)!.neighbors).toContain(b);
+    expect(nav.getPolygon(b)!.neighbors).toContain(a);
+  });
+
+  it('connect returns false for invalid ids', () => {
+    const nav = new NavMesh();
+    expect(nav.connect(99, 100)).toBe(false);
+  });
+
+  // ─── Pathfinding ──────────────────────────────────────────────────
+  it('finds direct path between connected polygons', () => {
+    const nav = new NavMesh();
+    const a = nav.addPolygon(tri(0, 0));
+    const b = nav.addPolygon(tri(3, 0));
+    nav.connect(a, b);
+    const path = nav.findPath(a, b);
+    expect(path).not.toBeNull();
+    expect(path!.polygonIds).toEqual([a, b]);
+    expect(path!.waypoints.length).toBe(2);
+  });
+
+  it('finds multi-hop path', () => {
+    const nav = new NavMesh();
+    const a = nav.addPolygon(tri(0, 0));
+    const b = nav.addPolygon(tri(3, 0));
+    const c = nav.addPolygon(tri(6, 0));
+    nav.connect(a, b);
+    nav.connect(b, c);
+    const path = nav.findPath(a, c);
+    expect(path).not.toBeNull();
+    expect(path!.polygonIds).toEqual([a, b, c]);
+  });
+
+  it('returns null when no path exists', () => {
+    const nav = new NavMesh();
+    const a = nav.addPolygon(tri(0, 0));
+    const b = nav.addPolygon(tri(100, 100));
+    // Not connected
+    expect(nav.findPath(a, b)).toBeNull();
+  });
+
+  it('same start/end returns zero-hop path', () => {
+    const nav = new NavMesh();
+    const a = nav.addPolygon(tri(0, 0));
+    const path = nav.findPath(a, a);
+    expect(path).not.toBeNull();
+    expect(path!.polygonIds).toEqual([a]);
+  });
+
+  // ─── Walkability ──────────────────────────────────────────────────
+  it('setWalkable blocks polygon from pathfinding', () => {
+    const nav = new NavMesh();
+    const a = nav.addPolygon(tri(0, 0));
+    const b = nav.addPolygon(tri(3, 0));
+    const c = nav.addPolygon(tri(6, 0));
+    nav.connect(a, b);
+    nav.connect(b, c);
+    nav.setWalkable(b, false);
+    expect(nav.findPath(a, c)).toBeNull();
+  });
+
+  it('findPath returns null if start is not walkable', () => {
+    const nav = new NavMesh();
+    const a = nav.addPolygon(tri(0, 0), false);
+    const b = nav.addPolygon(tri(3, 0));
+    nav.connect(a, b);
+    expect(nav.findPath(a, b)).toBeNull();
+  });
+
+  // ─── Cost ─────────────────────────────────────────────────────────
+  it('path prefers low-cost route', () => {
+    const nav = new NavMesh();
+    const a = nav.addPolygon(tri(0, 0));
+    const b = nav.addPolygon(tri(3, 0), true, 100); // expensive
+    const c = nav.addPolygon(tri(0, 3), true, 1); // cheap
+    const d = nav.addPolygon(tri(3, 3));
+    nav.connect(a, b);
+    nav.connect(b, d);
+    nav.connect(a, c);
+    nav.connect(c, d);
+    const path = nav.findPath(a, d);
+    expect(path).not.toBeNull();
+    expect(path!.polygonIds).toContain(c); // should go via cheap route
+  });
+
+  // ─── Smooth Path ──────────────────────────────────────────────────
+  it('smoothPath reduces waypoints when possible', () => {
+    const nav = new NavMesh();
+    const ids = Array.from({ length: 5 }, (_, i) => nav.addPolygon(tri(i * 3, 0)));
+    for (let i = 0; i < ids.length - 1; i++) nav.connect(ids[i], ids[i + 1]);
+    const path = nav.findPath(ids[0], ids[4])!;
+    const smoothed = nav.smoothPath(path);
+    expect(smoothed.waypoints.length).toBeLessThanOrEqual(path.waypoints.length);
+  });
+});

package/src/ai/__tests__/NavMesh.test.ts

@@ -0,0 +1,159 @@
+/**
+ * NavMesh Unit Tests
+ *
+ * Tests polygon management, A* pathfinding, path smoothing,
+ * walkability, and cost-based routing.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { NavMesh } from '../NavMesh';
+
+function tri(cx: number, cz: number): { x: number; z: number }[] {
+  return [
+    { x: cx - 1, z: cz - 1 },
+    { x: cx + 1, z: cz - 1 },
+    { x: cx, z: cz + 1 },
+  ];
+}
+
+describe('NavMesh', () => {
+  let mesh: NavMesh;
+
+  beforeEach(() => {
+    mesh = new NavMesh();
+  });
+
+  describe('polygon management', () => {
+    it('should add polygons and assign sequential IDs', () => {
+      const id0 = mesh.addPolygon(tri(0, 0));
+      const id1 = mesh.addPolygon(tri(5, 0));
+      expect(id0).toBe(0);
+      expect(id1).toBe(1);
+      expect(mesh.getPolygonCount()).toBe(2);
+    });
+
+    it('should compute center from vertices', () => {
+      const id = mesh.addPolygon([
+        { x: 0, z: 0 },
+        { x: 6, z: 0 },
+        { x: 3, z: 6 },
+      ]);
+      const poly = mesh.getPolygon(id)!;
+      expect(poly.center.x).toBeCloseTo(3);
+      expect(poly.center.z).toBeCloseTo(2);
+    });
+
+    it('should set walkability', () => {
+      const id = mesh.addPolygon(tri(0, 0));
+      mesh.setWalkable(id, false);
+      expect(mesh.getPolygon(id)!.walkable).toBe(false);
+    });
+  });
+
+  describe('connection', () => {
+    it('should connect two polygons bidirectionally', () => {
+      const a = mesh.addPolygon(tri(0, 0));
+      const b = mesh.addPolygon(tri(3, 0));
+      expect(mesh.connect(a, b)).toBe(true);
+      expect(mesh.getPolygon(a)!.neighbors).toContain(b);
+      expect(mesh.getPolygon(b)!.neighbors).toContain(a);
+    });
+
+    it('should return false for invalid polygon IDs', () => {
+      expect(mesh.connect(99, 100)).toBe(false);
+    });
+
+    it('should not duplicate neighbor entries', () => {
+      const a = mesh.addPolygon(tri(0, 0));
+      const b = mesh.addPolygon(tri(3, 0));
+      mesh.connect(a, b);
+      mesh.connect(a, b);
+      expect(mesh.getPolygon(a)!.neighbors.length).toBe(1);
+    });
+  });
+
+  describe('pathfinding', () => {
+    it('should find direct path between connected polys', () => {
+      const a = mesh.addPolygon(tri(0, 0));
+      const b = mesh.addPolygon(tri(3, 0));
+      mesh.connect(a, b);
+
+      const path = mesh.findPath(a, b);
+      expect(path).not.toBeNull();
+      expect(path!.polygonIds).toEqual([a, b]);
+      expect(path!.waypoints.length).toBe(2);
+    });
+
+    it('should find multi-hop path', () => {
+      const a = mesh.addPolygon(tri(0, 0));
+      const b = mesh.addPolygon(tri(3, 0));
+      const c = mesh.addPolygon(tri(6, 0));
+      mesh.connect(a, b);
+      mesh.connect(b, c);
+
+      const path = mesh.findPath(a, c);
+      expect(path).not.toBeNull();
+      expect(path!.polygonIds).toEqual([a, b, c]);
+    });
+
+    it('should return null for disconnected polys', () => {
+      const a = mesh.addPolygon(tri(0, 0));
+      mesh.addPolygon(tri(100, 0)); // not connected
+      expect(mesh.findPath(a, 1)).toBeNull();
+    });
+
+    it('should return null for non-walkable start/end', () => {
+      const a = mesh.addPolygon(tri(0, 0), false);
+      const b = mesh.addPolygon(tri(3, 0));
+      mesh.connect(a, b);
+      expect(mesh.findPath(a, b)).toBeNull();
+    });
+
+    it('should avoid non-walkable intermediate polys', () => {
+      const a = mesh.addPolygon(tri(0, 0));
+      const blocked = mesh.addPolygon(tri(3, 0), false);
+      const c = mesh.addPolygon(tri(6, 0));
+      mesh.connect(a, blocked);
+      mesh.connect(blocked, c);
+      expect(mesh.findPath(a, c)).toBeNull();
+    });
+
+    it('should prefer lower-cost paths', () => {
+      const a = mesh.addPolygon(tri(0, 0));
+      const cheapB = mesh.addPolygon(tri(3, 0), true, 1);
+      const expensiveC = mesh.addPolygon(tri(0, 3), true, 100);
+      const d = mesh.addPolygon(tri(6, 0));
+      mesh.connect(a, cheapB);
+      mesh.connect(a, expensiveC);
+      mesh.connect(cheapB, d);
+      mesh.connect(expensiveC, d);
+
+      const path = mesh.findPath(a, d);
+      expect(path).not.toBeNull();
+      expect(path!.polygonIds).toContain(cheapB);
+    });
+  });
+
+  describe('smoothPath', () => {
+    it('should reduce waypoints when possible', () => {
+      const a = mesh.addPolygon(tri(0, 0));
+      const b = mesh.addPolygon(tri(3, 0));
+      const c = mesh.addPolygon(tri(6, 0));
+      mesh.connect(a, b);
+      mesh.connect(b, c);
+
+      const path = mesh.findPath(a, c)!;
+      const smoothed = mesh.smoothPath(path);
+      expect(smoothed.waypoints.length).toBeLessThanOrEqual(path.waypoints.length);
+    });
+
+    it('should preserve single-segment paths', () => {
+      const a = mesh.addPolygon(tri(0, 0));
+      const b = mesh.addPolygon(tri(3, 0));
+      mesh.connect(a, b);
+      const path = mesh.findPath(a, b)!;
+      const smoothed = mesh.smoothPath(path);
+      expect(smoothed.waypoints.length).toBe(2);
+    });
+  });
+});

package/src/ai/__tests__/PerceptionSystem.prod.test.ts

@@ -0,0 +1,135 @@
+/**
+ * PerceptionSystem — Production Test Suite
+ *
+ * Covers: entity registration, stimulus management, sense types
+ * (sight/hearing/smell), range/FOV checks, memory/decay, queries.
+ */
+import { describe, it, expect } from 'vitest';
+import { PerceptionSystem, type SenseConfig, type Stimulus } from '../PerceptionSystem';
+
+function sightSense(range = 50, fov = 360, sensitivity = 1): SenseConfig {
+  return { type: 'sight', range, fov, sensitivity };
+}
+
+function stim(
+  id: string,
+  type: 'sight' | 'hearing' | 'smell' = 'sight',
+  x = 10,
+  y = 0,
+  z = 0,
+  intensity = 0.8
+): Stimulus {
+  return { id, type, sourceId: `src-${id}`, position: { x, y, z }, intensity, timestamp: 0 };
+}
+
+describe('PerceptionSystem — Production', () => {
+  // ─── Registration ─────────────────────────────────────────────────
+  it('registerEntity + getStimulusCount', () => {
+    const ps = new PerceptionSystem();
+    ps.registerEntity('guard', [sightSense()]);
+    ps.addStimulus(stim('s1'));
+    expect(ps.getStimulusCount()).toBe(1);
+  });
+
+  // ─── Detection Within Range ───────────────────────────────────────
+  it('detects stimulus within range', () => {
+    const ps = new PerceptionSystem();
+    ps.registerEntity('guard', [sightSense(50)]);
+    ps.addStimulus(stim('s1', 'sight', 10, 0, 0));
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(true);
+  });
+
+  it('does not detect stimulus out of range', () => {
+    const ps = new PerceptionSystem();
+    ps.registerEntity('guard', [sightSense(5)]);
+    ps.addStimulus(stim('s1', 'sight', 100, 0, 0));
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(false);
+  });
+
+  // ─── Sense Type Matching ──────────────────────────────────────────
+  it('only detects matching sense type', () => {
+    const ps = new PerceptionSystem();
+    ps.registerEntity('guard', [sightSense()]);
+    ps.addStimulus(stim('s1', 'hearing', 5, 0, 0)); // hearing stimulus but only sight sense
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(false);
+  });
+
+  // ─── FOV Check ────────────────────────────────────────────────────
+  it('FOV-limited sense detects in front', () => {
+    const ps = new PerceptionSystem();
+    ps.registerEntity('guard', [sightSense(50, 90)], 10); // 90° FOV
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 }); // facing +X
+    ps.addStimulus(stim('ahead', 'sight', 10, 0, 0)); // directly ahead
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 'ahead')).toBe(true);
+  });
+
+  it('FOV-limited sense misses behind', () => {
+    const ps = new PerceptionSystem();
+    ps.registerEntity('guard', [sightSense(50, 90)], 10);
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 }); // facing +X
+    ps.addStimulus(stim('behind', 'sight', -10, 0, 0)); // behind
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 'behind')).toBe(false);
+  });
+
+  // ─── Self-detection ───────────────────────────────────────────────
+  it('entity does not sense own stimuli', () => {
+    const ps = new PerceptionSystem();
+    ps.registerEntity('guard', [sightSense()]);
+    const s: Stimulus = {
+      id: 'self',
+      type: 'sight',
+      sourceId: 'guard',
+      position: { x: 0, y: 0, z: 0 },
+      intensity: 1,
+      timestamp: 0,
+    };
+    ps.addStimulus(s);
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 'self')).toBe(false);
+  });
+
+  // ─── Memory Decay ─────────────────────────────────────────────────
+  it('memory expires after memoryDuration', () => {
+    const ps = new PerceptionSystem();
+    ps.registerEntity('guard', [sightSense()], 5); // 5 second memory
+    ps.addStimulus(stim('s1'));
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(true);
+    ps.removeStimulus('s1');
+    ps.update(100); // way past memory duration
+    expect(ps.isAwareOf('guard', 's1')).toBe(false);
+  });
+
+  // ─── Queries ──────────────────────────────────────────────────────
+  it('getPerceivedStimuli returns all perceived', () => {
+    const ps = new PerceptionSystem();
+    ps.registerEntity('guard', [sightSense()]);
+    ps.addStimulus(stim('a', 'sight', 5, 0, 0));
+    ps.addStimulus(stim('b', 'sight', 8, 0, 0));
+    ps.update(1);
+    expect(ps.getPerceivedStimuli('guard').length).toBe(2);
+  });
+
+  it('getHighestPriority returns top awareness', () => {
+    const ps = new PerceptionSystem();
+    ps.registerEntity('guard', [sightSense(100, 360, 1)]);
+    ps.addStimulus(stim('far', 'sight', 40, 0, 0, 0.2));
+    ps.addStimulus(stim('near', 'sight', 2, 0, 0, 1.0));
+    ps.update(1);
+    const top = ps.getHighestPriority('guard');
+    expect(top).not.toBeNull();
+    expect(top!.id).toBe('near');
+  });
+
+  it('removeStimulus removes from world', () => {
+    const ps = new PerceptionSystem();
+    ps.addStimulus(stim('s1'));
+    ps.removeStimulus('s1');
+    expect(ps.getStimulusCount()).toBe(0);
+  });
+});

package/src/ai/__tests__/PerceptionSystem.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PerceptionSystem, type SenseConfig, type Stimulus } from '../PerceptionSystem';
+
+describe('PerceptionSystem', () => {
+  let ps: PerceptionSystem;
+
+  const sightSense: SenseConfig = { type: 'sight', range: 50, fov: 120, sensitivity: 1 };
+  const hearingSense: SenseConfig = { type: 'hearing', range: 100, fov: 360, sensitivity: 1 };
+
+  beforeEach(() => {
+    ps = new PerceptionSystem();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Registration
+  // ---------------------------------------------------------------------------
+
+  it('registerEntity and addStimulus track counts', () => {
+    ps.registerEntity('guard', [sightSense]);
+    ps.addStimulus({
+      id: 's1',
+      type: 'sight',
+      sourceId: 'player',
+      position: { x: 10, y: 0, z: 0 },
+      intensity: 0.8,
+      timestamp: 0,
+    });
+    expect(ps.getStimulusCount()).toBe(1);
+  });
+
+  it('removeStimulus decreases count', () => {
+    ps.addStimulus({
+      id: 's1',
+      type: 'sight',
+      sourceId: 'p',
+      position: { x: 0, y: 0, z: 0 },
+      intensity: 1,
+      timestamp: 0,
+    });
+    ps.removeStimulus('s1');
+    expect(ps.getStimulusCount()).toBe(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Perception Update — Range
+  // ---------------------------------------------------------------------------
+
+  it('perceives stimulus within range', () => {
+    ps.registerEntity('guard', [sightSense]);
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 });
+    ps.addStimulus({
+      id: 's1',
+      type: 'sight',
+      sourceId: 'player',
+      position: { x: 10, y: 0, z: 0 },
+      intensity: 0.9,
+      timestamp: 0,
+    });
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(true);
+  });
+
+  it('does not perceive stimulus out of range', () => {
+    ps.registerEntity('guard', [sightSense]); // range: 50
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 });
+    ps.addStimulus({
+      id: 's1',
+      type: 'sight',
+      sourceId: 'player',
+      position: { x: 200, y: 0, z: 0 },
+      intensity: 0.9,
+      timestamp: 0,
+    });
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(false);
+  });
+
+  // ---------------------------------------------------------------------------
+  // FOV Check
+  // ---------------------------------------------------------------------------
+
+  it('does not perceive stimulus behind entity (out of FOV)', () => {
+    ps.registerEntity('guard', [sightSense]); // fov: 120
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 }); // facing +X
+    ps.addStimulus({
+      id: 's1',
+      type: 'sight',
+      sourceId: 'player',
+      position: { x: -10, y: 0, z: 0 },
+      intensity: 1,
+      timestamp: 0,
+    }); // behind
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(false);
+  });
+
+  it('omnidirectional sense (hearing 360) perceives behind', () => {
+    ps.registerEntity('guard', [hearingSense]); // fov: 360
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 });
+    ps.addStimulus({
+      id: 's1',
+      type: 'hearing',
+      sourceId: 'player',
+      position: { x: -10, y: 0, z: 0 },
+      intensity: 0.8,
+      timestamp: 0,
+    });
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(true);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Self-Perception
+  // ---------------------------------------------------------------------------
+
+  it('entity does not perceive own stimuli', () => {
+    ps.registerEntity('guard', [sightSense]);
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 });
+    ps.addStimulus({
+      id: 's1',
+      type: 'sight',
+      sourceId: 'guard',
+      position: { x: 0, y: 0, z: 0 },
+      intensity: 1,
+      timestamp: 0,
+    });
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(false);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Sense Type Matching
+  // ---------------------------------------------------------------------------
+
+  it('only matching sense types are perceived', () => {
+    ps.registerEntity('guard', [sightSense]); // only sight
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 });
+    ps.addStimulus({
+      id: 's1',
+      type: 'hearing',
+      sourceId: 'player',
+      position: { x: 5, y: 0, z: 0 },
+      intensity: 1,
+      timestamp: 0,
+    });
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(false);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Awareness Growth
+  // ---------------------------------------------------------------------------
+
+  it('awareness increases with repeated exposure', () => {
+    ps.registerEntity('guard', [sightSense]);
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 });
+    ps.addStimulus({
+      id: 's1',
+      type: 'sight',
+      sourceId: 'player',
+      position: { x: 5, y: 0, z: 0 },
+      intensity: 0.5,
+      timestamp: 0,
+    });
+    ps.update(1);
+    const first = ps.getPerceivedStimuli('guard')[0].awareness;
+    ps.update(2);
+    const second = ps.getPerceivedStimuli('guard')[0].awareness;
+    expect(second).toBeGreaterThanOrEqual(first);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Memory Expiry
+  // ---------------------------------------------------------------------------
+
+  it('memories decay after memoryDuration', () => {
+    ps.registerEntity('guard', [sightSense], 5); // 5s memory
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 });
+    ps.addStimulus({
+      id: 's1',
+      type: 'sight',
+      sourceId: 'player',
+      position: { x: 5, y: 0, z: 0 },
+      intensity: 1,
+      timestamp: 0,
+    });
+    ps.update(1);
+    expect(ps.isAwareOf('guard', 's1')).toBe(true);
+    ps.removeStimulus('s1'); // remove the stimulus
+    ps.update(100); // much later
+    expect(ps.isAwareOf('guard', 's1')).toBe(false);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  it('getPerceivedStimuli returns all perceived', () => {
+    ps.registerEntity('guard', [sightSense]);
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 });
+    ps.addStimulus({
+      id: 'a',
+      type: 'sight',
+      sourceId: 'p1',
+      position: { x: 5, y: 0, z: 0 },
+      intensity: 0.5,
+      timestamp: 0,
+    });
+    ps.addStimulus({
+      id: 'b',
+      type: 'sight',
+      sourceId: 'p2',
+      position: { x: 10, y: 0, z: 0 },
+      intensity: 0.9,
+      timestamp: 0,
+    });
+    ps.update(1);
+    expect(ps.getPerceivedStimuli('guard').length).toBe(2);
+  });
+
+  it('getHighestPriority returns stimulus with highest awareness*intensity', () => {
+    ps.registerEntity('guard', [sightSense]);
+    ps.setEntityTransform('guard', { x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 });
+    ps.addStimulus({
+      id: 'weak',
+      type: 'sight',
+      sourceId: 'p1',
+      position: { x: 40, y: 0, z: 0 },
+      intensity: 0.1,
+      timestamp: 0,
+    });
+    ps.addStimulus({
+      id: 'strong',
+      type: 'sight',
+      sourceId: 'p2',
+      position: { x: 5, y: 0, z: 0 },
+      intensity: 1,
+      timestamp: 0,
+    });
+    ps.update(1);
+    const highest = ps.getHighestPriority('guard');
+    expect(highest).not.toBeNull();
+    expect(highest!.id).toBe('strong');
+  });
+
+  it('getHighestPriority returns null for no perceived stimuli', () => {
+    ps.registerEntity('guard', [sightSense]);
+    expect(ps.getHighestPriority('guard')).toBeNull();
+  });
+});