@holoscript/framework 6.0.3

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

@@ -0,0 +1,129 @@
+/**
+ * BehaviorSelector — Production Test Suite
+ *
+ * Covers: behavior management, priority/weighted/sequential selection,
+ * conditions, lockouts, fallbacks, execution, history tracking.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { BehaviorSelector, type Behavior } from '../BehaviorSelector';
+
+function makeBehavior(id: string, opts: Partial<Behavior> = {}): Behavior {
+  return {
+    id,
+    name: opts.name ?? id,
+    weight: opts.weight ?? 1,
+    priority: opts.priority ?? 1,
+    condition: opts.condition,
+    action: opts.action ?? vi.fn(),
+    lockoutMs: opts.lockoutMs ?? 0,
+    lastExecuted: opts.lastExecuted ?? -Infinity,
+  };
+}
+
+describe('BehaviorSelector — Production', () => {
+  // ─── Management ───────────────────────────────────────────────────
+  it('addBehavior + getBehaviorCount', () => {
+    const bs = new BehaviorSelector();
+    bs.addBehavior(makeBehavior('a'));
+    expect(bs.getBehaviorCount()).toBe(1);
+  });
+
+  it('removeBehavior removes by id', () => {
+    const bs = new BehaviorSelector();
+    bs.addBehavior(makeBehavior('a'));
+    bs.removeBehavior('a');
+    expect(bs.getBehaviorCount()).toBe(0);
+  });
+
+  // ─── Priority Selection ───────────────────────────────────────────
+  it('priority mode selects highest priority', () => {
+    const bs = new BehaviorSelector('priority');
+    bs.addBehavior(makeBehavior('low', { priority: 1 }));
+    bs.addBehavior(makeBehavior('high', { priority: 10 }));
+    const sel = bs.select();
+    expect(sel!.id).toBe('high');
+  });
+
+  // ─── Weighted Selection ───────────────────────────────────────────
+  it('weighted mode returns a behavior', () => {
+    const bs = new BehaviorSelector('weighted');
+    bs.addBehavior(makeBehavior('a', { weight: 10 }));
+    bs.addBehavior(makeBehavior('b', { weight: 1 }));
+    const sel = bs.select();
+    expect(sel).not.toBeNull();
+  });
+
+  // ─── Sequential Selection ─────────────────────────────────────────
+  it('sequential mode cycles through behaviors', () => {
+    const bs = new BehaviorSelector('sequential');
+    bs.addBehavior(makeBehavior('a'));
+    bs.addBehavior(makeBehavior('b'));
+    expect(bs.select()!.id).toBe('a');
+    expect(bs.select()!.id).toBe('b');
+    expect(bs.select()!.id).toBe('a');
+  });
+
+  // ─── Conditions ───────────────────────────────────────────────────
+  it('condition=false filters behavior', () => {
+    const bs = new BehaviorSelector('priority');
+    bs.addBehavior(makeBehavior('blocked', { priority: 10, condition: () => false }));
+    bs.addBehavior(makeBehavior('ok', { priority: 1 }));
+    expect(bs.select()!.id).toBe('ok');
+  });
+
+  // ─── Lockout ──────────────────────────────────────────────────────
+  it('lockout prevents re-selection within window', () => {
+    const bs = new BehaviorSelector('priority');
+    bs.addBehavior(makeBehavior('a', { priority: 10, lockoutMs: 1000, lastExecuted: 0 }));
+    bs.addBehavior(makeBehavior('b', { priority: 1 }));
+    bs.setTime(500); // within lockout
+    expect(bs.select()!.id).toBe('b');
+    bs.setTime(1001); // past lockout
+    expect(bs.select()!.id).toBe('a');
+  });
+
+  // ─── Fallback ─────────────────────────────────────────────────────
+  it('fallback used when no behaviors available', () => {
+    const bs = new BehaviorSelector('priority');
+    bs.addBehavior(makeBehavior('a', { condition: () => false }));
+    bs.setFallback(makeBehavior('fallback'));
+    expect(bs.select()!.id).toBe('fallback');
+  });
+
+  // ─── Execute ──────────────────────────────────────────────────────
+  it('execute calls action and returns id', () => {
+    const bs = new BehaviorSelector('priority');
+    const action = vi.fn();
+    bs.addBehavior(makeBehavior('a', { action, priority: 1 }));
+    const result = bs.execute();
+    expect(result).toBe('a');
+    expect(action).toHaveBeenCalled();
+  });
+
+  it('execute returns null when nothing available', () => {
+    const bs = new BehaviorSelector('priority');
+    expect(bs.execute()).toBeNull();
+  });
+
+  // ─── History ──────────────────────────────────────────────────────
+  it('history tracks executions', () => {
+    const bs = new BehaviorSelector('priority');
+    bs.addBehavior(makeBehavior('a'));
+    bs.setTime(100);
+    bs.execute();
+    const history = bs.getHistory();
+    expect(history.length).toBe(1);
+    expect(history[0].behaviorId).toBe('a');
+    expect(history[0].timestamp).toBe(100);
+  });
+
+  // ─── Mode Switching ───────────────────────────────────────────────
+  it('setMode changes selection strategy', () => {
+    const bs = new BehaviorSelector('priority');
+    bs.addBehavior(makeBehavior('a'));
+    bs.addBehavior(makeBehavior('b'));
+    bs.setMode('sequential');
+    expect(bs.select()!.id).toBe('a');
+    expect(bs.select()!.id).toBe('b');
+  });
+});

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

@@ -0,0 +1,132 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { BehaviorSelector, type Behavior } from '../BehaviorSelector';
+
+function beh(
+  id: string,
+  priority: number,
+  weight = 1,
+  lockoutMs = 0,
+  condition?: () => boolean
+): Behavior {
+  return {
+    id,
+    name: id,
+    weight,
+    priority,
+    condition,
+    action: () => {},
+    lockoutMs,
+    lastExecuted: -Infinity,
+  };
+}
+
+describe('BehaviorSelector', () => {
+  let bs: BehaviorSelector;
+
+  beforeEach(() => {
+    bs = new BehaviorSelector('priority');
+  });
+
+  // Management
+  it('addBehavior increases count', () => {
+    bs.addBehavior(beh('a', 1));
+    expect(bs.getBehaviorCount()).toBe(1);
+  });
+
+  it('removeBehavior removes', () => {
+    bs.addBehavior(beh('a', 1));
+    bs.removeBehavior('a');
+    expect(bs.getBehaviorCount()).toBe(0);
+  });
+
+  // Priority mode
+  it('select picks highest priority', () => {
+    bs.addBehavior(beh('low', 1));
+    bs.addBehavior(beh('high', 10));
+    const selected = bs.select();
+    expect(selected).not.toBeNull();
+    expect(selected!.id).toBe('high');
+  });
+
+  // Weighted mode
+  it('weighted mode selects behavior', () => {
+    bs.setMode('weighted');
+    bs.addBehavior(beh('a', 1, 100));
+    const selected = bs.select();
+    expect(selected).not.toBeNull();
+    expect(selected!.id).toBe('a');
+  });
+
+  // Sequential mode
+  it('sequential mode rotates', () => {
+    bs.setMode('sequential');
+    bs.addBehavior(beh('a', 1));
+    bs.addBehavior(beh('b', 1));
+    expect(bs.select()!.id).toBe('a');
+    expect(bs.select()!.id).toBe('b');
+    expect(bs.select()!.id).toBe('a'); // wraps
+  });
+
+  // Conditions
+  it('select skips behaviors that fail condition', () => {
+    bs.addBehavior(beh('blocked', 10, 1, 0, () => false));
+    bs.addBehavior(beh('ok', 5));
+    const selected = bs.select();
+    expect(selected!.id).toBe('ok');
+  });
+
+  // Lockout
+  it('lockout prevents re-selection', () => {
+    bs.addBehavior(beh('a', 10, 1, 1000));
+    bs.addBehavior(beh('b', 5));
+    bs.setTime(0);
+    bs.execute(); // executes 'a'
+    bs.setTime(500); // within lockout
+    const selected = bs.select();
+    expect(selected!.id).toBe('b');
+  });
+
+  it('lockout expires after time', () => {
+    bs.addBehavior(beh('a', 10, 1, 1000));
+    bs.setTime(0);
+    bs.execute();
+    bs.setTime(2000); // past lockout
+    expect(bs.select()!.id).toBe('a');
+  });
+
+  // Fallback
+  it('returns fallback when no behaviors available', () => {
+    bs.setFallback(beh('fallback', 0));
+    const selected = bs.select();
+    expect(selected!.id).toBe('fallback');
+  });
+
+  it('returns null when no fallback and empty', () => {
+    expect(bs.select()).toBeNull();
+  });
+
+  // Execute
+  it('execute runs action and returns id', () => {
+    let ran = false;
+    bs.addBehavior({
+      ...beh('a', 1),
+      action: () => {
+        ran = true;
+      },
+    });
+    const id = bs.execute();
+    expect(id).toBe('a');
+    expect(ran).toBe(true);
+  });
+
+  it('execute records history', () => {
+    bs.addBehavior(beh('a', 1));
+    bs.execute();
+    expect(bs.getHistory().length).toBe(1);
+    expect(bs.getHistory()[0].behaviorId).toBe('a');
+  });
+
+  it('execute returns null when nothing available', () => {
+    expect(bs.execute()).toBeNull();
+  });
+});

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

@@ -0,0 +1,266 @@
+/**
+ * BehaviorTree.prod.test.ts — Sprint CLXX
+ *
+ * Production tests for the BehaviorTree runner.
+ * API: new BehaviorTree()
+ *   .createTree(id, root, entity, blackboard?) → BTTreeDef
+ *   .removeTree(id)                            → boolean
+ *   .getTree(id)                               → BTTreeDef | undefined
+ *   .registerSubtree(name, root)               → void
+ *   .getSubtree(name)                          → BTNode | undefined
+ *   .tick(id, dt)                              → BTStatus
+ *   .tickAll(dt)                               → void
+ *   .abort(id)                                 → void
+ *   .enableTracing() / disableTracing()
+ *   .getTrace()                                → TraceEntry[]
+ *   .clearTrace()
+ *   .getTreeCount()                            → number
+ *   .getStatus(id)                             → BTStatus
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { BehaviorTree } from '../BehaviorTree';
+import { ActionNode, SequenceNode } from '../BTNodes';
+import type { BTStatus } from '../BTNodes';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function always(status: BTStatus) {
+  return new ActionNode(`always-${status}`, () => status);
+}
+
+let bt: BehaviorTree;
+
+beforeEach(() => {
+  bt = new BehaviorTree();
+});
+
+// ---------------------------------------------------------------------------
+// createTree / getTree / removeTree
+// ---------------------------------------------------------------------------
+
+describe('BehaviorTree', () => {
+  describe('createTree() / getTree() / removeTree()', () => {
+    it('createTree() registers and returns the tree', () => {
+      const tree = bt.createTree('t1', always('success'), 'agent-1');
+      expect(tree.id).toBe('t1');
+    });
+
+    it('getTree() retrieves the created tree', () => {
+      bt.createTree('t1', always('success'), 'agent-1');
+      expect(bt.getTree('t1')?.id).toBe('t1');
+    });
+
+    it('getTree() returns undefined for unknown id', () => {
+      expect(bt.getTree('nope')).toBeUndefined();
+    });
+
+    it('removeTree() deletes the tree', () => {
+      bt.createTree('t1', always('success'), 'agent-1');
+      expect(bt.removeTree('t1')).toBe(true);
+      expect(bt.getTree('t1')).toBeUndefined();
+    });
+
+    it('removeTree() returns false for unknown id', () => {
+      expect(bt.removeTree('no')).toBe(false);
+    });
+
+    it('createTree() initialises tickCount = 0 and status = ready', () => {
+      const tree = bt.createTree('t1', always('success'), 'agent-1');
+      expect(tree.tickCount).toBe(0);
+      expect(tree.status).toBe('ready');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // subtrees
+  // -------------------------------------------------------------------------
+
+  describe('registerSubtree() / getSubtree()', () => {
+    it('registers and retrieves a subtree', () => {
+      const root = always('success');
+      bt.registerSubtree('patrol', root);
+      expect(bt.getSubtree('patrol')).toBe(root);
+    });
+
+    it('returns undefined for unknown subtree', () => {
+      expect(bt.getSubtree('nope')).toBeUndefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // tick()
+  // -------------------------------------------------------------------------
+
+  describe('tick()', () => {
+    it('returns the root node status', () => {
+      bt.createTree('t1', always('success'), 'agent');
+      expect(bt.tick('t1', 0.016)).toBe('success');
+    });
+
+    it('returns failure for unknown tree id', () => {
+      expect(bt.tick('nope', 0.016)).toBe('failure');
+    });
+
+    it('increments tickCount on each tick', () => {
+      bt.createTree('t1', always('success'), 'a');
+      bt.tick('t1', 0.016);
+      bt.tick('t1', 0.016);
+      expect(bt.getTree('t1')?.tickCount).toBe(2);
+    });
+
+    it('updates tree.status after tick', () => {
+      bt.createTree('t1', always('running'), 'a');
+      bt.tick('t1', 0.016);
+      expect(bt.getStatus('t1')).toBe('running');
+    });
+
+    it('passes deltaTime in context to nodes', () => {
+      let receivedDt = -1;
+      const node = new ActionNode('dt-spy', (ctx) => {
+        receivedDt = ctx.deltaTime;
+        return 'success';
+      });
+      bt.createTree('t1', node, 'a');
+      bt.tick('t1', 0.033);
+      expect(receivedDt).toBe(0.033);
+    });
+
+    it('ticks a composite tree correctly (Sequence of successes)', () => {
+      const seq = new SequenceNode('seq', [always('success'), always('success')]);
+      bt.createTree('t1', seq, 'a');
+      expect(bt.tick('t1', 0.016)).toBe('success');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // tickAll()
+  // -------------------------------------------------------------------------
+
+  describe('tickAll()', () => {
+    it('ticks all registered trees', () => {
+      let count = 0;
+      const spy = new ActionNode('spy', () => {
+        count++;
+        return 'success';
+      });
+      bt.createTree('t1', spy, 'a');
+      bt.createTree('t2', spy, 'b');
+      bt.tickAll(0.016);
+      expect(count).toBe(2);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // abort()
+  // -------------------------------------------------------------------------
+
+  describe('abort()', () => {
+    it('marks the tree as aborted and sets status to failure', () => {
+      bt.createTree('t1', always('running'), 'a');
+      bt.abort('t1');
+      expect(bt.getTree('t1')?.aborted).toBe(true);
+      expect(bt.getStatus('t1')).toBe('failure');
+    });
+
+    it('abort() sets the tree status to failure (persists until next tick resolves it)', () => {
+      bt.createTree('t1', always('success'), 'a');
+      bt.abort('t1');
+      // abort sets status=failure immediately; getStatus reflects that
+      expect(bt.getStatus('t1')).toBe('failure');
+      // Next tick resets aborted=false and runs normally again
+      expect(bt.tick('t1', 0.016)).toBe('success');
+    });
+
+    it('abort() is a no-op for unknown id', () => {
+      expect(() => bt.abort('no-such-tree')).not.toThrow();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // tracing
+  // -------------------------------------------------------------------------
+
+  describe('enableTracing() / disableTracing() / getTrace() / clearTrace()', () => {
+    it('getTrace() returns empty array by default', () => {
+      expect(bt.getTrace()).toEqual([]);
+    });
+
+    it('tracing off: tick does not append entries', () => {
+      bt.createTree('t1', always('success'), 'a');
+      bt.tick('t1', 0.016);
+      expect(bt.getTrace().length).toBe(0);
+    });
+
+    it('tracing on: tick appends a trace entry', () => {
+      bt.enableTracing();
+      bt.createTree('t1', always('success'), 'a');
+      bt.tick('t1', 0.016);
+      expect(bt.getTrace().length).toBeGreaterThan(0);
+    });
+
+    it('trace entry has tree, node, status, tick fields', () => {
+      bt.enableTracing();
+      bt.createTree('t1', always('success'), 'a');
+      bt.tick('t1', 0.016);
+      const entry = bt.getTrace()[0];
+      expect(entry.tree).toBe('t1');
+      expect(entry.node).toBe('always-success');
+      expect(entry.status).toBe('success');
+      expect(typeof entry.tick).toBe('number');
+    });
+
+    it('disableTracing() stops accumulation', () => {
+      bt.enableTracing();
+      bt.createTree('t1', always('success'), 'a');
+      bt.tick('t1', 0.016);
+      bt.disableTracing();
+      bt.tick('t1', 0.016);
+      expect(bt.getTrace().length).toBe(1); // only first tick logged
+    });
+
+    it('clearTrace() empties the trace array', () => {
+      bt.enableTracing();
+      bt.createTree('t1', always('success'), 'a');
+      bt.tick('t1', 0.016);
+      bt.clearTrace();
+      expect(bt.getTrace().length).toBe(0);
+    });
+
+    it('getTrace() returns a copy', () => {
+      bt.enableTracing();
+      bt.createTree('t1', always('success'), 'a');
+      bt.tick('t1', 0.016);
+      const trace = bt.getTrace();
+      trace.pop();
+      expect(bt.getTrace().length).toBe(1);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // getTreeCount() / getStatus()
+  // -------------------------------------------------------------------------
+
+  describe('getTreeCount() / getStatus()', () => {
+    it('getTreeCount() is 0 initially', () => {
+      expect(bt.getTreeCount()).toBe(0);
+    });
+
+    it('getTreeCount() increments with each createTree()', () => {
+      bt.createTree('t1', always('success'), 'a');
+      bt.createTree('t2', always('success'), 'b');
+      expect(bt.getTreeCount()).toBe(2);
+    });
+
+    it('getStatus() returns ready before any tick', () => {
+      bt.createTree('t1', always('success'), 'a');
+      expect(bt.getStatus('t1')).toBe('ready');
+    });
+
+    it('getStatus() returns failure for unknown id', () => {
+      expect(bt.getStatus('no')).toBe('failure');
+    });
+  });
+});