@holoscript/framework 6.0.3

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

@@ -0,0 +1,171 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { GenerationCache, cachedGenerate } from '../GenerationCache';
+
+describe('GenerationCache', () => {
+  let cache: GenerationCache;
+
+  beforeEach(() => {
+    cache = new GenerationCache({ maxSize: 5, ttlMs: 60_000 });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Basic Set / Get
+  // ---------------------------------------------------------------------------
+
+  it('caches and retrieves an entry', () => {
+    cache.set('create a cube', 'const cube = new Cube();', 0.95, 'gpt-4');
+    const entry = cache.get('create a cube', 'gpt-4');
+    expect(entry).not.toBeNull();
+    expect(entry!.code).toBe('const cube = new Cube();');
+    expect(entry!.confidence).toBe(0.95);
+    expect(entry!.adapterName).toBe('gpt-4');
+  });
+
+  it('returns null for cache miss', () => {
+    expect(cache.get('unknown', 'gpt-4')).toBeNull();
+  });
+
+  it('same prompt different adapter is separate', () => {
+    cache.set('prompt', 'code1', 0.9, 'a');
+    cache.set('prompt', 'code2', 0.8, 'b');
+    expect(cache.get('prompt', 'a')!.code).toBe('code1');
+    expect(cache.get('prompt', 'b')!.code).toBe('code2');
+  });
+
+  // ---------------------------------------------------------------------------
+  // LRU Eviction
+  // ---------------------------------------------------------------------------
+
+  it('evicts oldest entry when maxSize exceeded', () => {
+    for (let i = 0; i < 5; i++) cache.set(`p${i}`, `r${i}`, 0.9, 'a');
+    cache.set('p5', 'r5', 0.9, 'a'); // should trigger eviction
+    const stats = cache.getStats();
+    // After eviction, at most maxSize entries remain
+    expect(stats.entriesCount).toBeLessThanOrEqual(6);
+    // The newest entry should be present
+    expect(cache.get('p5', 'a')).not.toBeNull();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Hit Tracking
+  // ---------------------------------------------------------------------------
+
+  it('increments hits on get', () => {
+    cache.set('prompt', 'code', 0.9, 'a');
+    cache.get('prompt', 'a');
+    cache.get('prompt', 'a');
+    const entry = cache.get('prompt', 'a');
+    expect(entry!.hits).toBe(3);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Statistics
+  // ---------------------------------------------------------------------------
+
+  it('tracks hits and misses', () => {
+    cache.set('a', '1', 0.9, 'x');
+    cache.get('a', 'x'); // hit
+    cache.get('b', 'x'); // miss
+    const stats = cache.getStats();
+    expect(stats.totalHits).toBe(1);
+    expect(stats.totalMisses).toBe(1);
+    expect(stats.hitRate).toBeCloseTo(0.5);
+  });
+
+  it('getStats returns zero rate with no queries', () => {
+    const stats = cache.getStats();
+    expect(stats.totalHits).toBe(0);
+    expect(stats.totalMisses).toBe(0);
+    expect(stats.hitRate).toBe(0);
+  });
+
+  it('stats include maxSize and entriesCount', () => {
+    cache.set('a', '1', 0.9, 'x');
+    const stats = cache.getStats();
+    expect(stats.maxSize).toBe(5);
+    expect(stats.entriesCount).toBe(1);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Remove
+  // ---------------------------------------------------------------------------
+
+  it('remove deletes specific entry', () => {
+    cache.set('a', '1', 0.9, 'x');
+    expect(cache.remove('a', 'x')).toBe(true);
+    expect(cache.get('a', 'x')).toBeNull();
+  });
+
+  it('remove returns false for missing entry', () => {
+    expect(cache.remove('nope', 'x')).toBe(false);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Clear
+  // ---------------------------------------------------------------------------
+
+  it('clear removes all entries and resets stats', () => {
+    cache.set('a', '1', 0.9, 'x');
+    cache.get('a', 'x');
+    cache.clear();
+    expect(cache.getStats().entriesCount).toBe(0);
+    expect(cache.getStats().totalHits).toBe(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Serialization
+  // ---------------------------------------------------------------------------
+
+  it('serialize / deserialize round-trip', () => {
+    cache.set('prompt1', 'code1', 0.9, 'x');
+    cache.set('prompt2', 'code2', 0.8, 'y');
+    const json = cache.serialize();
+    const cache2 = new GenerationCache({ maxSize: 5 });
+    cache2.deserialize(json);
+    expect(cache2.getStats().entriesCount).toBe(2);
+  });
+
+  // ---------------------------------------------------------------------------
+  // getEntries
+  // ---------------------------------------------------------------------------
+
+  it('getEntries returns all cached entries', () => {
+    cache.set('a', '1', 0.9, 'x');
+    cache.set('b', '2', 0.8, 'x');
+    expect(cache.getEntries()).toHaveLength(2);
+  });
+
+  // ---------------------------------------------------------------------------
+  // getSize
+  // ---------------------------------------------------------------------------
+
+  it('getSize returns positive number with entries', () => {
+    cache.set('a', '1', 0.9, 'x');
+    expect(cache.getSize()).toBeGreaterThan(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // cachedGenerate helper
+  // ---------------------------------------------------------------------------
+
+  it('cachedGenerate returns cached result on hit', async () => {
+    cache.set('prompt', 'cached_code', 0.95, 'adapter');
+    const result = await cachedGenerate('prompt', 'adapter', cache, async () => ({
+      holoScript: 'fresh_code',
+      aiConfidence: 0.5,
+    }));
+    expect(result.fromCache).toBe(true);
+    expect(result.code).toBe('cached_code');
+  });
+
+  it('cachedGenerate calls generator on miss', async () => {
+    const result = await cachedGenerate('new_prompt', 'adapter', cache, async () => ({
+      holoScript: 'generated',
+      aiConfidence: 0.9,
+    }));
+    expect(result.fromCache).toBe(false);
+    expect(result.code).toBe('generated');
+    // Should now be cached
+    expect(cache.get('new_prompt', 'adapter')).not.toBeNull();
+  });
+});

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

@@ -0,0 +1,189 @@
+/**
+ * GoalPlanner (GOAP) — Production Test Suite
+ *
+ * Covers: action/goal registration, plan generation, BFS pathfinding,
+ * preconditions, effects, cost optimization, plan execution, queries.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { GoalPlanner, type PlanAction, type Goal, type WorldState } from '../GoalPlanner';
+
+// ─── Helpers ────────────────────────────────────────────────────────
+function makeAction(
+  id: string,
+  cost: number,
+  preconditions: [string, boolean][],
+  effects: [string, boolean][]
+): PlanAction {
+  return {
+    id,
+    name: id,
+    cost,
+    preconditions: new Map(preconditions),
+    effects: new Map(effects),
+    execute: vi.fn(),
+  };
+}
+
+function makeGoal(id: string, priority: number, conditions: [string, boolean][]): Goal {
+  return { id, name: id, priority, conditions: new Map(conditions) };
+}
+
+describe('GoalPlanner — Production', () => {
+  // ─── Registration ─────────────────────────────────────────────────
+  it('addAction + getActionCount', () => {
+    const planner = new GoalPlanner();
+    planner.addAction(makeAction('chop', 1, [], [['hasWood', true]]));
+    expect(planner.getActionCount()).toBe(1);
+  });
+
+  it('addGoal + getGoalCount', () => {
+    const planner = new GoalPlanner();
+    planner.addGoal(makeGoal('buildHouse', 1, [['hasHouse', true]]));
+    expect(planner.getGoalCount()).toBe(1);
+  });
+
+  it('removeAction removes by id', () => {
+    const planner = new GoalPlanner();
+    planner.addAction(makeAction('chop', 1, [], [['hasWood', true]]));
+    planner.removeAction('chop');
+    expect(planner.getActionCount()).toBe(0);
+  });
+
+  it('removeGoal removes by id', () => {
+    const planner = new GoalPlanner();
+    planner.addGoal(makeGoal('build', 1, [['hasHouse', true]]));
+    planner.removeGoal('build');
+    expect(planner.getGoalCount()).toBe(0);
+  });
+
+  // ─── Plan: Simple ─────────────────────────────────────────────────
+  it('plans single-step solution', () => {
+    const planner = new GoalPlanner();
+    planner.addAction(makeAction('chop', 1, [], [['hasWood', true]]));
+    planner.addGoal(makeGoal('getWood', 1, [['hasWood', true]]));
+
+    const state: WorldState = new Map([['hasWood', false]]);
+    const plan = planner.plan(state);
+    expect(plan).not.toBeNull();
+    expect(plan!.actions.length).toBe(1);
+    expect(plan!.actions[0].id).toBe('chop');
+  });
+
+  // ─── Plan: Multi-step ─────────────────────────────────────────────
+  it('plans multi-step chain', () => {
+    const planner = new GoalPlanner();
+    planner.addAction(makeAction('getAxe', 1, [], [['hasAxe', true]]));
+    planner.addAction(makeAction('chop', 2, [['hasAxe', true]], [['hasWood', true]]));
+    planner.addGoal(makeGoal('getWood', 1, [['hasWood', true]]));
+
+    const state: WorldState = new Map([
+      ['hasAxe', false],
+      ['hasWood', false],
+    ]);
+    const plan = planner.plan(state);
+    expect(plan).not.toBeNull();
+    expect(plan!.actions.length).toBe(2);
+    expect(plan!.totalCost).toBe(3);
+  });
+
+  // ─── Plan: Already Satisfied ──────────────────────────────────────
+  it('returns zero-cost plan when goal already met', () => {
+    const planner = new GoalPlanner();
+    planner.addGoal(makeGoal('getWood', 1, [['hasWood', true]]));
+
+    const state: WorldState = new Map([['hasWood', true]]);
+    const plan = planner.plan(state);
+    expect(plan).not.toBeNull();
+    expect(plan!.actions.length).toBe(0);
+    expect(plan!.totalCost).toBe(0);
+  });
+
+  // ─── Plan: No Solution ────────────────────────────────────────────
+  it('returns null when no plan possible', () => {
+    const planner = new GoalPlanner();
+    planner.addGoal(makeGoal('fly', 1, [['canFly', true]]));
+
+    const state: WorldState = new Map([['canFly', false]]);
+    expect(planner.plan(state)).toBeNull();
+  });
+
+  // ─── Plan: Cost Optimization ──────────────────────────────────────
+  it('selects cheapest plan', () => {
+    const planner = new GoalPlanner();
+    planner.addAction(makeAction('expensive', 10, [], [['hasWood', true]]));
+    planner.addAction(makeAction('cheap', 1, [], [['hasWood', true]]));
+    planner.addGoal(makeGoal('getWood', 1, [['hasWood', true]]));
+
+    const state: WorldState = new Map([['hasWood', false]]);
+    const plan = planner.plan(state);
+    expect(plan!.totalCost).toBe(1);
+  });
+
+  // ─── Plan: Priority ───────────────────────────────────────────────
+  it('selects highest priority goal first', () => {
+    const planner = new GoalPlanner();
+    planner.addAction(makeAction('getFood', 1, [], [['hasFood', true]]));
+    planner.addAction(makeAction('getWater', 1, [], [['hasWater', true]]));
+    planner.addGoal(makeGoal('eat', 5, [['hasFood', true]]));
+    planner.addGoal(makeGoal('drink', 10, [['hasWater', true]]));
+
+    const state: WorldState = new Map([
+      ['hasFood', false],
+      ['hasWater', false],
+    ]);
+    const plan = planner.plan(state);
+    expect(plan!.goalId).toBe('drink'); // higher priority
+  });
+
+  // ─── Preconditions ────────────────────────────────────────────────
+  it('respects preconditions', () => {
+    const planner = new GoalPlanner();
+    planner.addAction(
+      makeAction(
+        'build',
+        5,
+        [
+          ['hasWood', true],
+          ['hasNails', true],
+        ],
+        [['hasHouse', true]]
+      )
+    );
+    planner.addGoal(makeGoal('shelter', 1, [['hasHouse', true]]));
+
+    // Missing preconditions, no other actions to get them
+    const state: WorldState = new Map([
+      ['hasWood', false],
+      ['hasNails', false],
+    ]);
+    expect(planner.plan(state)).toBeNull();
+  });
+
+  // ─── executePlan ──────────────────────────────────────────────────
+  it('executePlan calls all action execute functions', () => {
+    const planner = new GoalPlanner();
+    const a1 = makeAction('a', 1, [], [['x', true]]);
+    const a2 = makeAction('b', 1, [['x', true]], [['y', true]]);
+    planner.addAction(a1);
+    planner.addAction(a2);
+    planner.addGoal(makeGoal('g', 1, [['y', true]]));
+
+    const state: WorldState = new Map([
+      ['x', false],
+      ['y', false],
+    ]);
+    const plan = planner.plan(state);
+    expect(plan).not.toBeNull();
+    planner.executePlan(plan!);
+    for (const action of plan!.actions) {
+      expect(action.execute).toHaveBeenCalled();
+    }
+  });
+
+  // ─── No Goals ─────────────────────────────────────────────────────
+  it('returns null with no goals', () => {
+    const planner = new GoalPlanner();
+    const state: WorldState = new Map();
+    expect(planner.plan(state)).toBeNull();
+  });
+});

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

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { GoalPlanner, type PlanAction, type Goal, type WorldState } from '../GoalPlanner';
+
+function action(
+  id: string,
+  cost: number,
+  pre: Record<string, boolean>,
+  eff: Record<string, boolean>
+): PlanAction {
+  return {
+    id,
+    name: id,
+    cost,
+    preconditions: new Map(Object.entries(pre)),
+    effects: new Map(Object.entries(eff)),
+    execute: vi.fn(),
+  };
+}
+
+function goal(id: string, conditions: Record<string, boolean>, priority: number): Goal {
+  return { id, name: id, conditions: new Map(Object.entries(conditions)), priority };
+}
+
+describe('GoalPlanner', () => {
+  let planner: GoalPlanner;
+
+  beforeEach(() => {
+    planner = new GoalPlanner();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Registration
+  // ---------------------------------------------------------------------------
+
+  it('addAction increases action count', () => {
+    planner.addAction(action('a', 1, {}, {}));
+    expect(planner.getActionCount()).toBe(1);
+  });
+
+  it('addGoal increases goal count', () => {
+    planner.addGoal(goal('g', { win: true }, 1));
+    expect(planner.getGoalCount()).toBe(1);
+  });
+
+  it('removeAction decreases count', () => {
+    planner.addAction(action('a', 1, {}, {}));
+    planner.removeAction('a');
+    expect(planner.getActionCount()).toBe(0);
+  });
+
+  it('removeGoal decreases count', () => {
+    planner.addGoal(goal('g', { win: true }, 1));
+    planner.removeGoal('g');
+    expect(planner.getGoalCount()).toBe(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Planning
+  // ---------------------------------------------------------------------------
+
+  it('plan returns null when no goals', () => {
+    const state: WorldState = new Map();
+    expect(planner.plan(state)).toBeNull();
+  });
+
+  it('plan returns null when goal already met', () => {
+    planner.addGoal(goal('g', { happy: true }, 1));
+    const state: WorldState = new Map([['happy', true]]);
+    const result = planner.plan(state);
+    // Goal is already met, plan should contain zero actions
+    expect(result).not.toBeNull();
+    expect(result!.actions).toHaveLength(0);
+  });
+
+  it('plan finds single-step plan', () => {
+    planner.addAction(action('eat', 1, {}, { fed: true }));
+    planner.addGoal(goal('g', { fed: true }, 1));
+    const state: WorldState = new Map([['fed', false]]);
+    const result = planner.plan(state);
+    expect(result).not.toBeNull();
+    expect(result!.actions).toHaveLength(1);
+    expect(result!.actions[0].id).toBe('eat');
+  });
+
+  it('plan finds multi-step plan', () => {
+    planner.addAction(action('chop', 1, {}, { hasWood: true }));
+    planner.addAction(action('build', 2, { hasWood: true }, { hasShelter: true }));
+    planner.addGoal(goal('shelter', { hasShelter: true }, 1));
+    const state: WorldState = new Map([
+      ['hasWood', false],
+      ['hasShelter', false],
+    ]);
+    const result = planner.plan(state);
+    expect(result).not.toBeNull();
+    expect(result!.actions.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('plan prefers cheaper path', () => {
+    planner.addAction(action('expensive', 10, {}, { done: true }));
+    planner.addAction(action('cheap', 1, {}, { done: true }));
+    planner.addGoal(goal('g', { done: true }, 1));
+    const state: WorldState = new Map([['done', false]]);
+    const result = planner.plan(state);
+    expect(result).not.toBeNull();
+    expect(result!.totalCost).toBe(1);
+  });
+
+  it('plan returns null when no actions can satisfy goal', () => {
+    planner.addAction(action('noop', 1, {}, { irrelevant: true }));
+    planner.addGoal(goal('g', { impossible: true }, 1));
+    const state: WorldState = new Map();
+    expect(planner.plan(state)).toBeNull();
+  });
+
+  it('plan selects highest priority goal', () => {
+    planner.addAction(action('a1', 1, {}, { low: true }));
+    planner.addAction(action('a2', 1, {}, { high: true }));
+    planner.addGoal(goal('lo', { low: true }, 1));
+    planner.addGoal(goal('hi', { high: true }, 10));
+    const state: WorldState = new Map();
+    const result = planner.plan(state);
+    expect(result).not.toBeNull();
+    expect(result!.goalId).toBe('hi');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Execution
+  // ---------------------------------------------------------------------------
+
+  it('executePlan calls execute on each action', () => {
+    const a = action('a', 1, {}, {});
+    const b = action('b', 1, {}, {});
+    planner.executePlan({ actions: [a, b], totalCost: 2, goalId: 'g' });
+    expect(a.execute).toHaveBeenCalledTimes(1);
+    expect(b.execute).toHaveBeenCalledTimes(1);
+  });
+});