@holoscript/framework 6.0.3

package/src/knowledge/__tests__/knowledge-store-vector.test.ts

@@ -0,0 +1,291 @@
+/**
+ * Tests for KnowledgeStore vector embedding pipeline (FW-0.5).
+ *
+ * Covers: embedAndStore(), semanticSearch(), hybrid search, error fallback.
+ * Uses vi.fn() to mock global fetch — no real network calls.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { KnowledgeStore } from '../knowledge-store';
+import type { KnowledgeConfig, KnowledgeInsight } from '../../types';
+
+// ── Helpers ──
+
+function makeConfig(remote = true): KnowledgeConfig {
+  return {
+    persist: false,
+    ...(remote ? {
+      remoteUrl: 'https://mcp-orchestrator-production-45f9.up.railway.app',
+      remoteApiKey: 'test-api-key',
+    } : {}),
+  };
+}
+
+function makeInsight(overrides?: Partial<KnowledgeInsight>): KnowledgeInsight {
+  return {
+    type: 'wisdom',
+    content: 'Always use strict TypeScript',
+    domain: 'compilation',
+    confidence: 0.9,
+    source: 'test-agent',
+    ...overrides,
+  };
+}
+
+function mockFetchOk(data: unknown) {
+  return vi.fn().mockResolvedValue({
+    ok: true,
+    json: () => Promise.resolve(data),
+  });
+}
+
+function mockFetchFail() {
+  return vi.fn().mockResolvedValue({ ok: false, status: 500 });
+}
+
+function mockFetchThrow() {
+  return vi.fn().mockRejectedValue(new Error('Network error'));
+}
+
+// ── Tests ──
+
+describe('KnowledgeStore — Vector Embedding Pipeline', () => {
+  let originalFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  // ── embedAndStore ──
+
+  describe('embedAndStore', () => {
+    it('publishes locally and syncs to remote', async () => {
+      const fetchMock = mockFetchOk({ synced: 1, ids: ['remote-001'] });
+      globalThis.fetch = fetchMock;
+
+      const store = new KnowledgeStore(makeConfig());
+      const result = await store.embedAndStore(makeInsight(), 'agent-a');
+
+      expect(result.entryId).toMatch(/^W\./);
+      expect(result.synced).toBe(true);
+      expect(result.remoteId).toBe('remote-001');
+      expect(store.size).toBe(1);
+
+      // Verify fetch was called with correct endpoint and payload
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      const [url, opts] = fetchMock.mock.calls[0];
+      expect(url).toContain('/knowledge/sync');
+      expect(opts.headers['x-mcp-api-key']).toBe('test-api-key');
+
+      const body = JSON.parse(opts.body);
+      expect(body.workspace_id).toBe('ai-ecosystem');
+      expect(body.entries).toHaveLength(1);
+      expect(body.entries[0].content).toBe('Always use strict TypeScript');
+      expect(body.entries[0].metadata.domain).toBe('compilation');
+    });
+
+    it('publishes locally even when remote fails', async () => {
+      globalThis.fetch = mockFetchFail();
+
+      const store = new KnowledgeStore(makeConfig());
+      const result = await store.embedAndStore(makeInsight(), 'agent-a');
+
+      expect(result.entryId).toMatch(/^W\./);
+      expect(result.synced).toBe(false);
+      expect(result.remoteId).toBeUndefined();
+      expect(store.size).toBe(1);
+    });
+
+    it('publishes locally even when fetch throws', async () => {
+      globalThis.fetch = mockFetchThrow();
+
+      const store = new KnowledgeStore(makeConfig());
+      const result = await store.embedAndStore(makeInsight(), 'agent-a');
+
+      expect(result.entryId).toMatch(/^W\./);
+      expect(result.synced).toBe(false);
+      expect(store.size).toBe(1);
+    });
+
+    it('skips remote when no remoteUrl configured', async () => {
+      const fetchMock = vi.fn();
+      globalThis.fetch = fetchMock;
+
+      const store = new KnowledgeStore(makeConfig(false));
+      const result = await store.embedAndStore(makeInsight(), 'agent-a');
+
+      expect(result.entryId).toMatch(/^W\./);
+      expect(result.synced).toBe(false);
+      expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('deduplicates on repeated embed of same content', async () => {
+      globalThis.fetch = mockFetchOk({ synced: 1 });
+
+      const store = new KnowledgeStore(makeConfig());
+      const r1 = await store.embedAndStore(makeInsight(), 'agent-a');
+      const r2 = await store.embedAndStore(makeInsight(), 'agent-b');
+
+      // Same content = same entry (dedup)
+      expect(r1.entryId).toBe(r2.entryId);
+      expect(store.size).toBe(1);
+    });
+
+    it('includes provenance metadata in remote sync', async () => {
+      const fetchMock = mockFetchOk({ synced: 1 });
+      globalThis.fetch = fetchMock;
+
+      const store = new KnowledgeStore(makeConfig());
+      await store.embedAndStore(makeInsight(), 'agent-a', {
+        taskId: 'task-42',
+        cycleId: 'cycle-7',
+        provenanceHash: 'abc123',
+      });
+
+      const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+      expect(body.entries[0].metadata.taskId).toBe('task-42');
+      expect(body.entries[0].metadata.cycleId).toBe('cycle-7');
+      expect(body.entries[0].provenanceHash).toBe('abc123');
+    });
+  });
+
+  // ── semanticSearch ──
+
+  describe('semanticSearch', () => {
+    it('returns remote results when available', async () => {
+      const remoteEntries = [
+        { id: 'r1', type: 'wisdom', content: 'Use strict mode', metadata: { domain: 'compilation', confidence: 0.8 } },
+        { id: 'r2', type: 'pattern', content: 'Pattern matching', metadata: { domain: 'compilation', confidence: 0.7 } },
+      ];
+      globalThis.fetch = mockFetchOk(remoteEntries);
+
+      const store = new KnowledgeStore(makeConfig());
+      const results = await store.semanticSearch('strict typescript');
+
+      expect(results).toHaveLength(2);
+      expect(results[0].id).toBe('r1');
+      expect(results[0].content).toBe('Use strict mode');
+      expect(results[1].id).toBe('r2');
+    });
+
+    it('falls back to local keyword search when remote fails', async () => {
+      globalThis.fetch = mockFetchFail();
+
+      const store = new KnowledgeStore(makeConfig());
+      store.publish(makeInsight({ content: 'TypeScript strict mode is essential' }), 'agent-a');
+      store.publish(makeInsight({ content: 'Python type hints are optional' }), 'agent-b');
+
+      const results = await store.semanticSearch('strict typescript');
+
+      // Should find the local entry with matching keywords
+      expect(results.length).toBeGreaterThanOrEqual(1);
+      expect(results[0].content).toContain('strict');
+    });
+
+    it('falls back to local when fetch throws', async () => {
+      globalThis.fetch = mockFetchThrow();
+
+      const store = new KnowledgeStore(makeConfig());
+      store.publish(makeInsight({ content: 'TypeScript strict mode rocks' }), 'agent-a');
+
+      const results = await store.semanticSearch('strict typescript');
+      expect(results.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('falls back to local when no remote configured', async () => {
+      const store = new KnowledgeStore(makeConfig(false));
+      store.publish(makeInsight({ content: 'TypeScript strict mode rocks' }), 'agent-a');
+
+      const results = await store.semanticSearch('strict typescript');
+      expect(results.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('filters by type when specified', async () => {
+      const fetchMock = mockFetchOk([]);
+      globalThis.fetch = fetchMock;
+
+      const store = new KnowledgeStore(makeConfig());
+      await store.semanticSearch('rendering', { type: 'gotcha' });
+
+      const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+      expect(body.type).toBe('gotcha');
+    });
+
+    it('filters by minConfidence', async () => {
+      const remoteEntries = [
+        { id: 'r1', type: 'wisdom', content: 'High confidence', metadata: { confidence: 0.9, domain: 'general' } },
+        { id: 'r2', type: 'wisdom', content: 'Low confidence', metadata: { confidence: 0.3, domain: 'general' } },
+      ];
+      globalThis.fetch = mockFetchOk(remoteEntries);
+
+      const store = new KnowledgeStore(makeConfig());
+      const results = await store.semanticSearch('confidence', { minConfidence: 0.5 });
+
+      expect(results).toHaveLength(1);
+      expect(results[0].id).toBe('r1');
+    });
+
+    it('respects limit parameter', async () => {
+      const remoteEntries = Array.from({ length: 20 }, (_, i) => ({
+        id: `r${i}`,
+        type: 'wisdom',
+        content: `Entry ${i}`,
+        metadata: { domain: 'general', confidence: 0.5 },
+      }));
+      globalThis.fetch = mockFetchOk(remoteEntries);
+
+      const store = new KnowledgeStore(makeConfig());
+      const results = await store.semanticSearch('entry', { limit: 5 });
+
+      expect(results).toHaveLength(5);
+    });
+
+    it('hybrid search merges remote + local, deduped by ID', async () => {
+      const remoteEntries = [
+        { id: 'r1', type: 'wisdom', content: 'Remote only', metadata: { domain: 'general', confidence: 0.9 } },
+        { id: 'shared', type: 'wisdom', content: 'Remote version', metadata: { domain: 'general', confidence: 0.8 } },
+      ];
+      globalThis.fetch = mockFetchOk(remoteEntries);
+
+      const store = new KnowledgeStore(makeConfig());
+      // Publish a local entry that has the same ID as a remote entry
+      const local = store.publish(makeInsight({ content: 'Local entry about general topics' }), 'agent-a');
+
+      const results = await store.semanticSearch('general topics', { hybridSearch: true, limit: 10 });
+
+      // Should contain remote entries + local entries, no duplicate IDs
+      const ids = results.map(r => r.id);
+      const uniqueIds = new Set(ids);
+      expect(ids.length).toBe(uniqueIds.size);
+
+      // Remote entries should be present
+      expect(ids).toContain('r1');
+    });
+
+    it('hybrid search: remote wins on ID conflict', async () => {
+      // Create a store with a local entry
+      const store = new KnowledgeStore(makeConfig());
+      store.publish(makeInsight({ content: 'Local version of knowledge' }), 'agent-a');
+      const localId = store.all()[0].id;
+
+      // Remote returns an entry with the same ID but different content
+      const remoteEntries = [
+        { id: localId, type: 'wisdom', content: 'Remote version of knowledge', metadata: { domain: 'compilation', confidence: 0.95 } },
+      ];
+      globalThis.fetch = mockFetchOk(remoteEntries);
+
+      const results = await store.semanticSearch('knowledge', { hybridSearch: true });
+
+      // The entry with localId should appear exactly once
+      const matching = results.filter(r => r.id === localId);
+      expect(matching).toHaveLength(1);
+      // Remote wins (appears first in merge)
+      expect(matching[0].content).toBe('Remote version of knowledge');
+    });
+  });
+});

package/src/knowledge/brain.ts

@@ -0,0 +1,167 @@
+/**
+ * Knowledge Brain — Domain-specific consolidation, excitability, half-lives.
+ *
+ * Absorbed from mcp-server/src/holomesh/types.ts (V9/V11 neuroscience model).
+ * The knowledge store uses these for search ranking, decay, and consolidation.
+ */
+
+// ── Domains ──
+
+export const KNOWLEDGE_DOMAINS = [
+  'security',
+  'rendering',
+  'agents',
+  'compilation',
+  'general',
+] as const;
+
+export type KnowledgeDomain = (typeof KNOWLEDGE_DOMAINS)[number];
+
+// ── Consolidation Config ──
+
+export interface DomainConsolidationConfig {
+  hotBufferTTL: number;
+  sleepFrequencyMs: number;
+  maxEntries: number;
+  competitionMetric: 'citation_count' | 'query_frequency' | 'peer_corroboration';
+  downscaleFactor: number;
+  minCorroborations: number;
+}
+
+export const DOMAIN_CONSOLIDATION: Record<KnowledgeDomain, DomainConsolidationConfig> = {
+  security: {
+    hotBufferTTL: 1 * 60 * 60 * 1000,
+    sleepFrequencyMs: 6 * 60 * 60 * 1000,
+    maxEntries: 50,
+    competitionMetric: 'peer_corroboration',
+    downscaleFactor: 0.85,
+    minCorroborations: 2,
+  },
+  rendering: {
+    hotBufferTTL: 24 * 60 * 60 * 1000,
+    sleepFrequencyMs: 24 * 60 * 60 * 1000,
+    maxEntries: 200,
+    competitionMetric: 'query_frequency',
+    downscaleFactor: 0.95,
+    minCorroborations: 1,
+  },
+  agents: {
+    hotBufferTTL: 12 * 60 * 60 * 1000,
+    sleepFrequencyMs: 12 * 60 * 60 * 1000,
+    maxEntries: 150,
+    competitionMetric: 'query_frequency',
+    downscaleFactor: 0.90,
+    minCorroborations: 1,
+  },
+  compilation: {
+    hotBufferTTL: 12 * 60 * 60 * 1000,
+    sleepFrequencyMs: 12 * 60 * 60 * 1000,
+    maxEntries: 100,
+    competitionMetric: 'citation_count',
+    downscaleFactor: 0.90,
+    minCorroborations: 1,
+  },
+  general: {
+    hotBufferTTL: 6 * 60 * 60 * 1000,
+    sleepFrequencyMs: 12 * 60 * 60 * 1000,
+    maxEntries: 300,
+    competitionMetric: 'query_frequency',
+    downscaleFactor: 0.92,
+    minCorroborations: 1,
+  },
+};
+
+// ── Half-Lives ──
+
+export const DOMAIN_HALF_LIVES: Record<KnowledgeDomain, number> = {
+  security: 2 * 24 * 60 * 60 * 1000,      // 2 days
+  rendering: 14 * 24 * 60 * 60 * 1000,     // 14 days
+  agents: 7 * 24 * 60 * 60 * 1000,         // 7 days
+  compilation: 21 * 24 * 60 * 60 * 1000,   // 21 days
+  general: 7 * 24 * 60 * 60 * 1000,        // 7 days
+};
+
+// ── Hot Buffer ──
+
+export interface HotBufferEntry {
+  id: string;
+  domain: KnowledgeDomain;
+  content: string;
+  type: string;
+  authorDid: string;
+  tags: string[];
+  ingestedAt: number;
+  corroborations: string[];
+  sourcePeerDid: string;
+}
+
+// ── Excitability ──
+
+export interface ExcitabilityMetadata {
+  queryCount: number;
+  citationCount: number;
+  corroborationCount: number;
+  excitability: number;
+  lastRetrievedAt: number;
+  lastReconsolidatedAt: number;
+  consolidationSurvivals: number;
+}
+
+/** Compute excitability score from metadata. */
+export function computeExcitability(meta: Omit<ExcitabilityMetadata, 'excitability'>): number {
+  return (
+    2 * meta.queryCount +
+    3 * meta.citationCount +
+    1.5 * meta.corroborationCount +
+    0.5 * meta.consolidationSurvivals
+  );
+}
+
+/** Apply domain half-life decay to a score. */
+export function applyHalfLifeDecay(score: number, ageMs: number, domain: KnowledgeDomain): number {
+  const halfLife = DOMAIN_HALF_LIVES[domain] || DOMAIN_HALF_LIVES.general;
+  return score * Math.pow(0.5, ageMs / halfLife);
+}
+
+// ── Consolidation Result ──
+
+export interface ConsolidationResult {
+  domain: KnowledgeDomain;
+  promoted: number;
+  merged: number;
+  evicted: number;
+  dropped: number;
+  downscaleFactor: number;
+  consolidatedAt: number;
+}
+
+// ── Reconsolidation ──
+
+export interface ReconsolidationEvent {
+  entryId: string;
+  domain: KnowledgeDomain;
+  retrievedAt: number;
+  excitabilityDelta: number;
+  windowOpen: boolean;
+  windowClosesAt: number;
+}
+
+/** Default reconsolidation window duration (5 minutes). */
+export const RECONSOLIDATION_WINDOW_MS = 5 * 60 * 1000;
+
+/** Create a reconsolidation event when an entry is retrieved. */
+export function triggerReconsolidation(
+  entryId: string,
+  domain: KnowledgeDomain,
+  excitabilityDelta: number
+): ReconsolidationEvent {
+  const now = Date.now();
+  return {
+    entryId,
+    domain,
+    retrievedAt: now,
+    excitabilityDelta,
+    windowOpen: true,
+    windowClosesAt: now + RECONSOLIDATION_WINDOW_MS,
+  };
+}