cognitive-core 0.1.2 → 0.2.0

package/tests/memory/coherence.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect } from 'vitest';
+import { CoherenceChecker } from '../../src/memory/coherence.js';
+import { createObservation } from '../../src/types/knowledge.js';
+import type { KnowledgeNote } from '../../src/types/knowledge.js';
+
+function makeNote(opts: {
+  id?: string;
+  body: string;
+  domain?: string[];
+  entities?: string[];
+}): KnowledgeNote {
+  return createObservation({
+    id: opts.id ?? `k-${crypto.randomUUID().slice(0, 8)}`,
+    title: 'Test note',
+    body: opts.body,
+    domain: opts.domain ?? ['testing'],
+    entities: opts.entities ?? ['vitest'],
+    confidence: 0.7,
+    source: { origin: 'extracted' },
+  });
+}
+
+describe('CoherenceChecker', () => {
+  const checker = new CoherenceChecker();
+
+  describe('coherent notes', () => {
+    it('should pass check for non-contradictory notes', async () => {
+      const newNote = makeNote({
+        body: 'Always use TypeScript for type safety in production code',
+        entities: ['typescript'],
+        domain: ['typescript'],
+      });
+      const existingNotes = [
+        makeNote({
+          body: 'TypeScript provides excellent type checking capabilities',
+          entities: ['typescript'],
+          domain: ['typescript'],
+        }),
+        makeNote({
+          body: 'Enable strict mode in tsconfig for better type safety',
+          entities: ['typescript'],
+          domain: ['typescript'],
+        }),
+      ];
+
+      const result = await checker.check(newNote, existingNotes);
+
+      expect(result.isCoherent).toBe(true);
+      expect(result.contradictions).toHaveLength(0);
+    });
+
+    it('should skip notes in different domains', async () => {
+      const newNote = makeNote({
+        body: 'Always use strict mode in Python for better error handling',
+        entities: ['python'],
+        domain: ['python'],
+      });
+      const existingNotes = [
+        makeNote({
+          body: 'Never use strict mode — it slows down development',
+          entities: ['javascript'],
+          domain: ['javascript'],
+        }),
+      ];
+
+      const result = await checker.check(newNote, existingNotes);
+
+      expect(result.isCoherent).toBe(true);
+      expect(result.contradictions).toHaveLength(0);
+    });
+  });
+
+  describe('contradictory notes', () => {
+    it('should detect "always use X" vs "never use X" contradiction', async () => {
+      const newNote = makeNote({
+        body: 'Always use semicolons in TypeScript code for consistency',
+        entities: ['typescript'],
+        domain: ['typescript'],
+      });
+      const existingNotes = [
+        makeNote({
+          body: 'Never use semicolons in TypeScript code — the parser handles it automatically',
+          entities: ['typescript'],
+          domain: ['typescript'],
+        }),
+      ];
+
+      const result = await checker.check(newNote, existingNotes);
+
+      expect(result.isCoherent).toBe(false);
+      expect(result.contradictions.length).toBeGreaterThan(0);
+      expect(result.contradictions[0].residualEnergy).toBeGreaterThan(0.2);
+    });
+
+    it('should detect "use X" vs "avoid X" contradiction', async () => {
+      const newNote = makeNote({
+        body: 'For TypeScript projects, use the any type when working with dynamic data structures',
+        entities: ['typescript'],
+        domain: ['typescript'],
+      });
+      const existingNotes = [
+        makeNote({
+          body: 'For TypeScript projects, avoid the any type when working with dynamic data structures',
+          entities: ['typescript'],
+          domain: ['typescript'],
+        }),
+      ];
+
+      const result = await checker.check(newNote, existingNotes);
+
+      expect(result.isCoherent).toBe(false);
+      expect(result.contradictions.length).toBeGreaterThan(0);
+    });
+
+    it('should detect "do X" vs "don\'t X" contradiction', async () => {
+      const newNote = makeNote({
+        body: 'When configuring eslint rules for the project, do enable strict type checking',
+        entities: ['eslint'],
+        domain: ['tooling'],
+      });
+      const existingNotes = [
+        makeNote({
+          body: "When configuring eslint rules for the project, don't enable strict type checking",
+          entities: ['eslint'],
+          domain: ['tooling'],
+        }),
+      ];
+
+      const result = await checker.check(newNote, existingNotes);
+
+      expect(result.isCoherent).toBe(false);
+      expect(result.contradictions.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('same-entity filtering', () => {
+    it('should compare notes with the same entities', async () => {
+      const newNote = makeNote({
+        body: 'Always use vitest for testing TypeScript projects',
+        entities: ['vitest'],
+        domain: ['testing'],
+      });
+      const existingNotes = [
+        makeNote({
+          body: 'Never use vitest for testing TypeScript projects — use jest instead',
+          entities: ['vitest'],
+          domain: ['testing'],
+        }),
+        makeNote({
+          body: 'Deploy applications to production every Friday',
+          entities: ['deployment'],
+          domain: ['devops'],
+        }),
+      ];
+
+      const result = await checker.check(newNote, existingNotes);
+
+      // Should only find contradiction with vitest note, not deployment note
+      expect(result.isCoherent).toBe(false);
+      expect(result.contradictions.length).toBe(1);
+    });
+  });
+
+  describe('global energy', () => {
+    it('should return 0 for a single note', () => {
+      const notes = [
+        makeNote({ body: 'TypeScript is great', domain: ['typescript'] }),
+      ];
+
+      const energy = checker.computeGlobalEnergy(notes);
+      expect(energy).toBe(0);
+    });
+
+    it('should increase energy with more contradictions', () => {
+      const coherentNotes = [
+        makeNote({
+          body: 'Use TypeScript for type safety',
+          domain: ['typescript'],
+          entities: ['typescript'],
+        }),
+        makeNote({
+          body: 'TypeScript provides compile-time checking',
+          domain: ['typescript'],
+          entities: ['typescript'],
+        }),
+      ];
+
+      const contradictoryNotes = [
+        makeNote({
+          body: 'Always use strict TypeScript types for safety',
+          domain: ['typescript'],
+          entities: ['typescript'],
+        }),
+        makeNote({
+          body: 'Never use strict TypeScript types — they slow development',
+          domain: ['typescript'],
+          entities: ['typescript'],
+        }),
+      ];
+
+      const coherentEnergy = checker.computeGlobalEnergy(coherentNotes);
+      const contradictoryEnergy = checker.computeGlobalEnergy(contradictoryNotes);
+
+      expect(contradictoryEnergy).toBeGreaterThan(coherentEnergy);
+    });
+  });
+
+  describe('configuration', () => {
+    it('should respect maxComparisons', async () => {
+      const checker2 = new CoherenceChecker({ maxComparisons: 1 });
+      const newNote = makeNote({
+        body: 'Always use semicolons for consistency',
+        entities: ['typescript'],
+        domain: ['typescript'],
+      });
+      // Create many existing notes — only 1 should be compared
+      const existingNotes = Array.from({ length: 10 }, (_, i) =>
+        makeNote({
+          id: `note-${i}`,
+          body: `Never use semicolons — note ${i} for consistency`,
+          entities: ['typescript'],
+          domain: ['typescript'],
+        })
+      );
+
+      const result = await checker2.check(newNote, existingNotes);
+
+      // Should find at most 1 contradiction since maxComparisons=1
+      expect(result.contradictions.length).toBeLessThanOrEqual(1);
+    });
+  });
+});

package/tests/memory/experience.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { ExperienceMemory } from '../../src/memory/experience.js';
 import { createExperience, type Experience } from '../../src/types/memory.js';
+import { createSqlitePersistence } from '../../src/persistence/index.js';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
@@ -8,15 +9,19 @@ import { tmpdir } from 'node:os';
 describe('ExperienceMemory', () => {
   let tempDir: string;
   let memory: ExperienceMemory;
+  let persistence: any;
 
   beforeEach(async () => {
     tempDir = await mkdtemp(join(tmpdir(), 'atlas-test-'));
-    memory = new ExperienceMemory(tempDir);
+    persistence = createSqlitePersistence({ baseDir: tempDir });
+    await persistence.init();
+    memory = new ExperienceMemory(persistence);
     await memory.init();
   });
 
   afterEach(async () => {
     await memory.close();
+    persistence.close();
     await rm(tempDir, { recursive: true, force: true });
   });
 
@@ -184,8 +189,8 @@ describe('ExperienceMemory', () => {
       await memory.add(exp);
       await memory.close();
 
-      // Create new memory instance
-      const memory2 = new ExperienceMemory(tempDir);
+      // Create new memory instance from the same persistence (shared SQLite DB)
+      const memory2 = new ExperienceMemory(persistence);
       await memory2.init();
 
       const retrieved = await memory2.get(exp.id);

package/tests/memory/playbook.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { PlaybookLibrary, createPlaybookLibrary } from '../../src/memory/playbook.js';
 import type { Playbook } from '../../src/types/playbook.js';
+import { createSqlitePersistence } from '../../src/persistence/index.js';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
@@ -8,15 +9,19 @@ import { tmpdir } from 'node:os';
 describe('PlaybookLibrary', () => {
   let tempDir: string;
   let library: PlaybookLibrary;
+  let persistence: any;
 
   beforeEach(async () => {
     tempDir = await mkdtemp(join(tmpdir(), 'atlas-test-'));
-    library = createPlaybookLibrary(tempDir);
+    persistence = createSqlitePersistence({ baseDir: tempDir });
+    await persistence.init();
+    library = createPlaybookLibrary(persistence);
     await library.init();
   });
 
   afterEach(async () => {
     await library.close();
+    persistence.close();
     await rm(tempDir, { recursive: true, force: true });
   });
 
@@ -322,6 +327,164 @@ describe('PlaybookLibrary', () => {
     });
   });
 
+  describe('stability-plasticity', () => {
+    it('should dampen confidence changes for high consolidationStrength', async () => {
+      // Create a highly consolidated playbook
+      const consolidated = createSamplePlaybook({
+        name: 'consolidated',
+        confidence: 0.7,
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 50,
+          failureCount: 2,
+          consolidationStrength: 5,
+        },
+      });
+      await library.add(consolidated);
+
+      // Create a fresh playbook
+      const fresh = createSamplePlaybook({
+        name: 'fresh',
+        confidence: 0.7,
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 0,
+          failureCount: 0,
+          consolidationStrength: 0,
+        },
+      });
+      await library.add(fresh);
+
+      // Apply failure to both
+      await library.recordFailure(consolidated.id, 'traj-1', 'test', 'test fail');
+      await library.recordFailure(fresh.id, 'traj-2', 'test', 'test fail');
+
+      const updatedConsolidated = await library.get(consolidated.id);
+      const updatedFresh = await library.get(fresh.id);
+
+      // Both should decrease, but consolidated should decrease less
+      const consolidatedDelta = 0.7 - updatedConsolidated!.confidence;
+      const freshDelta = 0.7 - updatedFresh!.confidence;
+      expect(consolidatedDelta).toBeLessThan(freshDelta);
+    });
+
+    it('should behave as before when consolidationStrength is 0', async () => {
+      // A playbook with no consolidation should update like the original EMA
+      const playbook = createSamplePlaybook({
+        confidence: 0.5,
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 0,
+          failureCount: 0,
+          consolidationStrength: 0,
+        },
+      });
+      await library.add(playbook);
+
+      await library.recordSuccess(playbook.id, 'traj-1');
+
+      const updated = await library.get(playbook.id);
+      // With cs=0: dampedDelta = rawDelta / (1 + 0) = rawDelta
+      // rawDelta = (1 - 0.5) * 0.1 = 0.05
+      // new confidence = 0.5 + 0.05 = 0.55
+      expect(updated!.confidence).toBeCloseTo(0.55, 2);
+    });
+
+    it('should grow consolidationStrength on success', async () => {
+      const playbook = createSamplePlaybook({
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 0,
+          failureCount: 0,
+          consolidationStrength: 0,
+        },
+      });
+      await library.add(playbook);
+
+      await library.recordSuccess(playbook.id, 'traj-1');
+      const after1 = await library.get(playbook.id);
+      expect(after1!.evolution.consolidationStrength).toBeCloseTo(0.05, 3);
+
+      await library.recordSuccess(playbook.id, 'traj-2');
+      const after2 = await library.get(playbook.id);
+      expect(after2!.evolution.consolidationStrength).toBeCloseTo(0.10, 3);
+    });
+
+    it('should not reduce consolidationStrength on failure', async () => {
+      const playbook = createSamplePlaybook({
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 10,
+          failureCount: 0,
+          consolidationStrength: 2.0,
+        },
+      });
+      await library.add(playbook);
+
+      await library.recordFailure(playbook.id, 'traj-1', 'test', 'failed');
+      const updated = await library.get(playbook.id);
+      // consolidationStrength should remain at 2.0 (failures don't reduce it)
+      expect(updated!.evolution.consolidationStrength).toBe(2.0);
+    });
+
+    it('should cap consolidationStrength at 10', async () => {
+      const playbook = createSamplePlaybook({
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 100,
+          failureCount: 0,
+          consolidationStrength: 9.98,
+        },
+      });
+      await library.add(playbook);
+
+      await library.recordSuccess(playbook.id, 'traj-1');
+      const updated = await library.get(playbook.id);
+      expect(updated!.evolution.consolidationStrength).toBeLessThanOrEqual(10);
+    });
+
+    it('should backward compat — missing consolidationStrength defaults to 0', async () => {
+      // Playbook without consolidationStrength field
+      const playbook = createSamplePlaybook({
+        confidence: 0.5,
+        evolution: {
+          version: '1.0.0',
+          createdFrom: [],
+          failures: [],
+          refinements: [],
+          successCount: 0,
+          failureCount: 0,
+          // No consolidationStrength or domainBreadth
+        },
+      });
+      await library.add(playbook);
+
+      await library.recordSuccess(playbook.id, 'traj-1');
+      const updated = await library.get(playbook.id);
+      // Should still work, same as cs=0
+      expect(updated!.confidence).toBeCloseTo(0.55, 2);
+      expect(updated!.evolution.consolidationStrength).toBeCloseTo(0.05, 3);
+    });
+  });
+
   describe('count and getAll', () => {
     it('should return correct counts', async () => {
       expect(await library.count()).toBe(0);
@@ -335,4 +498,147 @@ describe('PlaybookLibrary', () => {
       expect(all).toHaveLength(2);
     });
   });
+
+  describe('MMR diversity', () => {
+    it('should match pure relevance ranking when lambda=1.0', async () => {
+      await library.add(createSamplePlaybook({
+        name: 'pb-a',
+        applicability: {
+          situations: ['Fix TypeScript type errors in production code'],
+          triggers: ['TS2322'],
+          antiPatterns: [],
+          domains: ['typescript'],
+        },
+        guidance: {
+          strategy: 'Analyze and fix type mismatches',
+          tactics: [],
+          steps: [],
+        },
+      }));
+      await library.add(createSamplePlaybook({
+        name: 'pb-b',
+        applicability: {
+          situations: ['Fix TypeScript import errors'],
+          triggers: ['import'],
+          antiPatterns: [],
+          domains: ['typescript'],
+        },
+        guidance: {
+          strategy: 'Check and resolve import paths',
+          tactics: [],
+          steps: [],
+        },
+      }));
+
+      // lambda=1.0 should give same order as no MMR
+      const pureRelevance = await library.findMatching('TypeScript type errors', { k: 2 });
+      const mmr1 = await library.findMatching('TypeScript type errors', { k: 2, lambda: 1.0 });
+
+      expect(pureRelevance.length).toBe(mmr1.length);
+      // Same top result
+      expect(pureRelevance[0].playbook.name).toBe(mmr1[0].playbook.name);
+    });
+
+    it('should diversify results when lambda is low', async () => {
+      // Add two very similar playbooks and one different
+      await library.add(createSamplePlaybook({
+        name: 'similar-1',
+        applicability: {
+          situations: ['Debug TypeScript type error in code'],
+          triggers: ['type error'],
+          antiPatterns: [],
+          domains: ['typescript'],
+        },
+        guidance: {
+          strategy: 'Read the full error message and trace back to the source type declaration',
+          tactics: [],
+          steps: [],
+        },
+      }));
+      await library.add(createSamplePlaybook({
+        name: 'similar-2',
+        applicability: {
+          situations: ['Debug TypeScript type error in tests'],
+          triggers: ['type error'],
+          antiPatterns: [],
+          domains: ['typescript'],
+        },
+        guidance: {
+          strategy: 'Read the full error message and trace back to the source type declaration',
+          tactics: [],
+          steps: [],
+        },
+      }));
+      await library.add(createSamplePlaybook({
+        name: 'different',
+        applicability: {
+          situations: ['Debug TypeScript type error using alternative approach'],
+          triggers: ['type error'],
+          antiPatterns: [],
+          domains: ['typescript'],
+        },
+        guidance: {
+          strategy: 'Use the TypeScript compiler API to programmatically analyze types',
+          tactics: [],
+          steps: [],
+        },
+      }));
+
+      // With low lambda, MMR should prefer the diverse playbook over the near-duplicate
+      const diverseResults = await library.findMatching('TypeScript type error', {
+        k: 3,
+        lambda: 0.3,
+      });
+
+      expect(diverseResults.length).toBe(3);
+      // The "different" strategy playbook should appear in the top results
+      const names = diverseResults.map((r) => r.playbook.name);
+      expect(names).toContain('different');
+    });
+
+    it('should avoid returning near-duplicates with strong diversity bias', async () => {
+      // Add 3 playbooks with identical strategies
+      for (let i = 0; i < 3; i++) {
+        await library.add(createSamplePlaybook({
+          name: `clone-${i}`,
+          applicability: {
+            situations: ['Resolve eslint warnings in codebase'],
+            triggers: ['eslint warning'],
+            antiPatterns: [],
+            domains: ['typescript'],
+          },
+          guidance: {
+            strategy: 'Run eslint with auto-fix flag',
+            tactics: [],
+            steps: [],
+          },
+        }));
+      }
+
+      // Add one unique playbook
+      await library.add(createSamplePlaybook({
+        name: 'unique-lint',
+        applicability: {
+          situations: ['Resolve eslint warnings using custom rules'],
+          triggers: ['eslint warning'],
+          antiPatterns: [],
+          domains: ['typescript'],
+        },
+        guidance: {
+          strategy: 'Create custom eslint rule to prevent the warning pattern',
+          tactics: [],
+          steps: [],
+        },
+      }));
+
+      // With diversity bias, the unique one should appear by position 2
+      const results = await library.findMatching('eslint warnings', {
+        k: 2,
+        lambda: 0.3,
+      });
+
+      const names = results.map((r) => r.playbook.name);
+      expect(names).toContain('unique-lint');
+    });
+  });
 });

package/tests/memory/provenance.test.ts

@@ -3,6 +3,7 @@ import { PlaybookLibrary, createPlaybookLibrary } from '../../src/memory/playboo
 import { loadCuratedPlaybooks, type CuratedPlaybookFile } from '../../src/memory/curated-loader.js';
 import type { Playbook, PlaybookProvenance } from '../../src/types/playbook.js';
 import { createPlaybook } from '../../src/types/playbook.js';
+import { createSqlitePersistence } from '../../src/persistence/index.js';
 import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
@@ -10,15 +11,19 @@ import { tmpdir } from 'node:os';
 describe('Playbook Provenance', () => {
   let tempDir: string;
   let library: PlaybookLibrary;
+  let persistence: any;
 
   beforeEach(async () => {
     tempDir = await mkdtemp(join(tmpdir(), 'atlas-prov-test-'));
-    library = createPlaybookLibrary(tempDir);
+    persistence = createSqlitePersistence({ baseDir: tempDir });
+    await persistence.init();
+    library = createPlaybookLibrary(persistence);
     await library.init();
   });
 
   afterEach(async () => {
     await library.close();
+    persistence.close();
     await rm(tempDir, { recursive: true, force: true });
   });
 
@@ -373,17 +378,21 @@ describe('Curated Playbook Loader', () => {
   let tempDir: string;
   let curatedDir: string;
   let library: PlaybookLibrary;
+  let persistence: any;
 
   beforeEach(async () => {
     tempDir = await mkdtemp(join(tmpdir(), 'atlas-curated-test-'));
     curatedDir = join(tempDir, 'curated');
     await mkdir(curatedDir, { recursive: true });
-    library = createPlaybookLibrary(tempDir);
+    persistence = createSqlitePersistence({ baseDir: tempDir });
+    await persistence.init();
+    library = createPlaybookLibrary(persistence);
     await library.init();
   });
 
   afterEach(async () => {
     await library.close();
+    persistence.close();
     await rm(tempDir, { recursive: true, force: true });
   });