claude-memory-layer 1.0.26 → 1.0.28

package/tests/core/embedding-maintenance-service.test.ts

@@ -0,0 +1,282 @@
+import * as path from 'path';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  createEmbeddingMaintenanceService,
+  type EmbeddingMaintenanceFileSystem
+} from '../../src/core/engine/embedding-maintenance-service.js';
+
+function event(id: string, content = `content for ${id}`) {
+  return { id, content };
+}
+
+function createHarness(options?: {
+  currentModel?: string;
+  vectorCount?: number;
+  files?: Record<string, string>;
+  workerRunning?: boolean;
+  nullWorker?: boolean;
+  events?: Array<{ id: string; content: string }>;
+}) {
+  const storagePath = '/memory-root/project-a';
+  const metaPath = path.join(storagePath, 'embedding-meta.json');
+  const files = new Map<string, string>(Object.entries(options?.files ?? {}));
+  const calls: string[] = [];
+
+  const fileSystem: EmbeddingMaintenanceFileSystem = {
+    existsSync: vi.fn((targetPath: string) => files.has(targetPath)),
+    readFileSync: vi.fn((targetPath: string) => files.get(targetPath) ?? ''),
+    writeFileSync: vi.fn((targetPath: string, content: string) => {
+      files.set(targetPath, content);
+    })
+  };
+
+  const initialize = vi.fn(async () => {
+    calls.push('initialize');
+  });
+  const vectorStore = {
+    count: vi.fn(async () => options?.vectorCount ?? 0),
+    clearAll: vi.fn(async () => {
+      calls.push('clear-vectors');
+    })
+  };
+  const events = options?.events ?? [];
+  const eventStore = {
+    clearEmbeddingOutbox: vi.fn(async () => {
+      calls.push('clear-outbox');
+    }),
+    getEventsPage: vi.fn(async (limit: number, offset: number) => events.slice(offset, offset + limit)),
+    enqueueForEmbedding: vi.fn(async (eventId: string, _content: string) => {
+      calls.push(`enqueue:${eventId}`);
+    })
+  };
+  const worker = {
+    isRunning: vi.fn(() => options?.workerRunning ?? false),
+    stop: vi.fn(() => {
+      calls.push('stop-worker');
+    }),
+    start: vi.fn(() => {
+      calls.push('start-worker');
+    })
+  };
+
+  const service = createEmbeddingMaintenanceService({
+    storagePath,
+    initialize,
+    getEmbeddingModelName: vi.fn(() => options?.currentModel ?? 'embedding-model-a'),
+    vectorStore,
+    eventStore,
+    getVectorWorker: () => (options?.nullWorker ? null : worker),
+    fileSystem
+  });
+
+  return {
+    service,
+    storagePath,
+    metaPath,
+    files,
+    calls,
+    fileSystem,
+    initialize,
+    vectorStore,
+    eventStore,
+    worker
+  };
+}
+
+describe('EmbeddingMaintenanceService', () => {
+  it('initializes embedding metadata when no prior vectors exist', async () => {
+    const h = createHarness({ vectorCount: 0 });
+
+    const result = await h.service.ensureEmbeddingModelForImport();
+
+    expect(result).toEqual({
+      changed: false,
+      previousModel: null,
+      currentModel: 'embedding-model-a',
+      enqueued: 0,
+      reason: 'initialized-meta'
+    });
+    expect(h.initialize).toHaveBeenCalledTimes(1);
+    expect(h.vectorStore.count).toHaveBeenCalledTimes(1);
+    expect(h.vectorStore.clearAll).not.toHaveBeenCalled();
+    expect(h.eventStore.clearEmbeddingOutbox).not.toHaveBeenCalled();
+    expect(JSON.parse(h.files.get(h.metaPath)!)).toMatchObject({
+      model: 'embedding-model-a',
+      updatedAt: expect.any(String)
+    });
+  });
+
+  it('returns unchanged when stored metadata already matches the current model', async () => {
+    const metaPath = path.join('/memory-root/project-a', 'embedding-meta.json');
+    const h = createHarness({
+      vectorCount: 5,
+      files: {
+        [metaPath]: JSON.stringify({ model: 'embedding-model-a', updatedAt: '2026-05-02T00:00:00.000Z' })
+      }
+    });
+
+    const result = await h.service.ensureEmbeddingModelForImport();
+
+    expect(result).toEqual({
+      changed: false,
+      previousModel: 'embedding-model-a',
+      currentModel: 'embedding-model-a',
+      enqueued: 0
+    });
+    expect(h.fileSystem.writeFileSync).not.toHaveBeenCalled();
+    expect(h.vectorStore.clearAll).not.toHaveBeenCalled();
+    expect(h.eventStore.clearEmbeddingOutbox).not.toHaveBeenCalled();
+  });
+
+  it('reports a dry-run model mismatch without clearing vectors or outbox state', async () => {
+    const metaPath = path.join('/memory-root/project-a', 'embedding-meta.json');
+    const h = createHarness({
+      currentModel: 'embedding-model-b',
+      vectorCount: 2,
+      files: {
+        [metaPath]: JSON.stringify({ model: 'embedding-model-a' })
+      }
+    });
+
+    const result = await h.service.ensureEmbeddingModelForImport({ autoMigrate: false });
+
+    expect(result).toEqual({
+      changed: true,
+      previousModel: 'embedding-model-a',
+      currentModel: 'embedding-model-b',
+      enqueued: 0,
+      reason: 'model-mismatch'
+    });
+    expect(h.vectorStore.clearAll).not.toHaveBeenCalled();
+    expect(h.eventStore.clearEmbeddingOutbox).not.toHaveBeenCalled();
+    expect(h.eventStore.enqueueForEmbedding).not.toHaveBeenCalled();
+  });
+
+  it('reports legacy vectors without metadata as a dry-run migration requirement', async () => {
+    const h = createHarness({ vectorCount: 3 });
+
+    const result = await h.service.ensureEmbeddingModelForImport({ autoMigrate: false });
+
+    expect(result).toEqual({
+      changed: true,
+      previousModel: null,
+      currentModel: 'embedding-model-a',
+      enqueued: 0,
+      reason: 'legacy-vectors-without-meta'
+    });
+    expect(h.fileSystem.writeFileSync).not.toHaveBeenCalled();
+    expect(h.vectorStore.clearAll).not.toHaveBeenCalled();
+  });
+
+  it('migrates vectors by clearing indexes, re-enqueueing events, and restarting a running worker', async () => {
+    const metaPath = path.join('/memory-root/project-a', 'embedding-meta.json');
+    const h = createHarness({
+      currentModel: 'embedding-model-b',
+      vectorCount: 10,
+      workerRunning: true,
+      files: {
+        [metaPath]: JSON.stringify({ model: 'embedding-model-a' })
+      },
+      events: [event('e1', 'first memory'), event('e2', 'second memory')]
+    });
+
+    const result = await h.service.ensureEmbeddingModelForImport();
+
+    expect(result).toEqual({
+      changed: true,
+      previousModel: 'embedding-model-a',
+      currentModel: 'embedding-model-b',
+      enqueued: 2,
+      reason: 'model-mismatch'
+    });
+    expect(h.calls).toEqual([
+      'initialize',
+      'stop-worker',
+      'clear-vectors',
+      'clear-outbox',
+      'enqueue:e1',
+      'enqueue:e2',
+      'start-worker'
+    ]);
+    expect(h.eventStore.getEventsPage).toHaveBeenCalledWith(1000, 0);
+    expect(h.eventStore.enqueueForEmbedding).toHaveBeenNthCalledWith(1, 'e1', 'first memory');
+    expect(h.eventStore.enqueueForEmbedding).toHaveBeenNthCalledWith(2, 'e2', 'second memory');
+    expect(JSON.parse(h.files.get(h.metaPath)!)).toMatchObject({
+      model: 'embedding-model-b',
+      previousModel: 'embedding-model-a',
+      migratedAt: expect.any(String),
+      enqueued: 2
+    });
+  });
+
+  it('auto-migrates legacy vectors without metadata and does not restart an idle worker', async () => {
+    const h = createHarness({
+      vectorCount: 3,
+      workerRunning: false,
+      events: [event('legacy-1', 'legacy memory')]
+    });
+
+    const result = await h.service.ensureEmbeddingModelForImport();
+
+    expect(result).toEqual({
+      changed: true,
+      previousModel: null,
+      currentModel: 'embedding-model-a',
+      enqueued: 1,
+      reason: 'legacy-vectors-without-meta'
+    });
+    expect(h.worker.stop).not.toHaveBeenCalled();
+    expect(h.worker.start).not.toHaveBeenCalled();
+    expect(h.calls).toEqual(['initialize', 'clear-vectors', 'clear-outbox', 'enqueue:legacy-1']);
+    expect(JSON.parse(h.files.get(h.metaPath)!)).toMatchObject({
+      model: 'embedding-model-a',
+      previousModel: null,
+      migratedAt: expect.any(String),
+      enqueued: 1
+    });
+  });
+
+  it('re-enqueues events across page boundaries during migration', async () => {
+    const metaPath = path.join('/memory-root/project-a', 'embedding-meta.json');
+    const events = Array.from({ length: 1001 }, (_, index) => event(`event-${index + 1}`));
+    const h = createHarness({
+      currentModel: 'embedding-model-b',
+      vectorCount: 1001,
+      files: {
+        [metaPath]: JSON.stringify({ model: 'embedding-model-a' })
+      },
+      events
+    });
+
+    const result = await h.service.ensureEmbeddingModelForImport();
+
+    expect(result.enqueued).toBe(1001);
+    expect(h.eventStore.getEventsPage).toHaveBeenNthCalledWith(1, 1000, 0);
+    expect(h.eventStore.getEventsPage).toHaveBeenNthCalledWith(2, 1000, 1000);
+    expect(h.eventStore.getEventsPage).toHaveBeenCalledTimes(2);
+    expect(h.eventStore.enqueueForEmbedding).toHaveBeenCalledTimes(1001);
+    expect(h.eventStore.enqueueForEmbedding).toHaveBeenNthCalledWith(1001, 'event-1001', 'content for event-1001');
+  });
+
+  it('migrates without worker lifecycle calls when no vector worker is available', async () => {
+    const metaPath = path.join('/memory-root/project-a', 'embedding-meta.json');
+    const h = createHarness({
+      currentModel: 'embedding-model-b',
+      vectorCount: 1,
+      nullWorker: true,
+      files: {
+        [metaPath]: JSON.stringify({ model: 'embedding-model-a' })
+      },
+      events: [event('e1')]
+    });
+
+    const result = await h.service.ensureEmbeddingModelForImport();
+
+    expect(result.enqueued).toBe(1);
+    expect(h.calls).toEqual(['initialize', 'clear-vectors', 'clear-outbox', 'enqueue:e1']);
+    expect(h.worker.isRunning).not.toHaveBeenCalled();
+    expect(h.worker.stop).not.toHaveBeenCalled();
+    expect(h.worker.start).not.toHaveBeenCalled();
+  });
+});

package/tests/{evidence-aligner.test.ts → core/evidence-aligner.test.ts}

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { EvidenceAligner } from '../src/core/evidence-aligner.js';
+import { EvidenceAligner } from '../../src/core/evidence-aligner.js';
 
 describe('EvidenceAligner', () => {
   const aligner = new EvidenceAligner();

package/tests/core/external-market-context.test.ts

@@ -0,0 +1,209 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  fetchExternalMarketContext,
+  renderExternalMarketContextReport
+} from '../../src/core/external-market-context.js';
+
+const originalEnv = process.env;
+
+function dartList(filings: Array<Record<string, string>>) {
+  return { status: '000', message: '정상', list: filings, page_count: filings.length, total_count: filings.length };
+}
+
+function fredObservations(value: string) {
+  return { observations: [{ date: '2026-05-01', value }] };
+}
+
+describe('external market context', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    process.env = {
+      ...originalEnv,
+      DART_API_KEY: 'dk',
+      FRED_API_KEY: 'fk',
+      FINNHUB_API_KEY: 'hk'
+    };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    vi.restoreAllMocks();
+  });
+
+  it('fails closed for invalid explicit core providers before network fetch', async () => {
+    globalThis.fetch = vi.fn(async () => {
+      throw new Error('fetch should not be called for invalid providers');
+    }) as never;
+
+    await expect(fetchExternalMarketContext({ providers: ['bogus'] as never })).rejects.toThrow('Invalid providers');
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+
+  it('skips missing provider keys without external fetches', async () => {
+    process.env = {
+      ...originalEnv,
+      DART_API_KEY: '',
+      FRED_API_KEY: '',
+      FINNHUB_API_KEY: ''
+    };
+    globalThis.fetch = vi.fn(async () => {
+      throw new Error('fetch should not be called when all provider keys are missing');
+    }) as never;
+
+    const report = await fetchExternalMarketContext({
+      company: '삼성전자',
+      dartCorpCode: '00126380',
+      symbol: '005930.KS',
+      providers: ['dart', 'fred', 'finnhub']
+    });
+
+    expect(report.dart).toMatchObject({ status: 'skipped', warnings: ['DART_API_KEY is not set'] });
+    expect(report.fred).toMatchObject({ status: 'skipped', warnings: ['FRED_API_KEY is not set'] });
+    expect(report.finnhub).toMatchObject({ status: 'skipped', warnings: ['FINNHUB_API_KEY is not set'] });
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+
+  it('treats DART status 013 as an empty successful filing result', async () => {
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({ status: '013', message: '조회된 데이타가 없습니다.' }), { status: 200 })) as never;
+
+    const report = await fetchExternalMarketContext({
+      company: '삼성전자',
+      dartCorpCode: '00126380',
+      providers: ['dart'],
+      now: new Date('2026-05-06T00:00:00Z')
+    });
+
+    expect(report.dart).toMatchObject({ status: 'ok', filings: [], displayedFilings: [] });
+    expect(report.analysis?.marketSnapshot?.coverage.dart).toMatchObject({
+      status: 'ok',
+      filingsAnalyzed: 0,
+      renderedFilings: 0,
+      confidence: 'exact-corp-code'
+    });
+  });
+
+  it('adds abort signals to provider requests and caps large FRED series lists', async () => {
+    const fetchSignals: Array<AbortSignal | null | undefined> = [];
+    globalThis.fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      fetchSignals.push(init?.signal);
+      const url = String(input);
+      if (url.includes('opendart.fss.or.kr')) return new Response(JSON.stringify(dartList([])), { status: 200 });
+      if (url.includes('stlouisfed.org')) return new Response(JSON.stringify(fredObservations('5.25')), { status: 200 });
+      if (url.includes('finnhub.io')) return new Response(JSON.stringify({ name: 'Samsung Electronics', ticker: '005930.KS' }), { status: 200 });
+      throw new Error(`unexpected URL ${url}`);
+    }) as never;
+    const fredSeries = Array.from({ length: 15 }, (_, index) => `SERIES${index}`);
+
+    const report = await fetchExternalMarketContext({
+      company: '삼성전자',
+      dartCorpCode: '00126380',
+      symbol: '005930.KS',
+      providers: ['dart', 'fred', 'finnhub'],
+      fredSeries
+    });
+
+    expect(report.query.fredSeries).toHaveLength(10);
+    expect(report.fred?.series).toHaveLength(10);
+    expect(report.fred?.warnings?.some((warning) => warning.includes('truncated to 10'))).toBe(true);
+    expect(globalThis.fetch).toHaveBeenCalledTimes(12);
+    expect(fetchSignals.every((signal) => signal instanceof AbortSignal)).toBe(true);
+  });
+
+  it('treats an empty Finnhub profile as skipped instead of emitting profile evidence', async () => {
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({}), { status: 200 })) as never;
+
+    const report = await fetchExternalMarketContext({ symbol: 'NOPE', providers: ['finnhub'] });
+    const snapshot = report.analysis?.marketSnapshot;
+
+    expect(report.finnhub).toMatchObject({ status: 'skipped', warnings: ['Finnhub returned no profile data'] });
+    expect(report.finnhub?.profile).toBeUndefined();
+    expect(snapshot?.coverage.finnhub).toMatchObject({ status: 'skipped', hasProfile: false });
+    expect(snapshot?.catalysts.some((item) => item.evidence.some((evidence) => evidence.provider === 'finnhub'))).toBe(false);
+  });
+
+  it('builds a structured multi-provider MarketContextSnapshot with bull, bear, risk, and catalyst evidence', async () => {
+    const filings = [
+      { corp_name: '삼성전자', rcept_no: '20260501000001', report_nm: '단일판매ㆍ공급계약체결', flr_nm: '삼성전자', rcept_dt: '20260501', rm: '' },
+      { corp_name: '삼성전자', rcept_no: '20260502000002', report_nm: '영업(잠정)실적(공정공시)', flr_nm: '삼성전자', rcept_dt: '20260502', rm: '' },
+      { corp_name: '삼성전자', rcept_no: '20260503000003', report_nm: '소송등의제기ㆍ신청(경영권분쟁소송)', flr_nm: '삼성전자', rcept_dt: '20260503', rm: '' },
+      { corp_name: '삼성전자', rcept_no: '20260504000004', report_nm: '유상증자결정', flr_nm: '삼성전자', rcept_dt: '20260504', rm: '' }
+    ];
+    globalThis.fetch = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('opendart.fss.or.kr')) return new Response(JSON.stringify(dartList(filings)), { status: 200 });
+      if (url.includes('stlouisfed.org')) return new Response(JSON.stringify(fredObservations('5.25')), { status: 200 });
+      if (url.includes('finnhub.io')) return new Response(JSON.stringify({ name: 'Samsung Electronics', ticker: '005930.KS', exchange: 'KRX', marketCapitalization: 450000, finnhubIndustry: 'Technology' }), { status: 200 });
+      throw new Error(`unexpected URL ${url}`);
+    }) as never;
+
+    const report = await fetchExternalMarketContext({
+      company: '삼성전자',
+      dartCorpCode: '00126380',
+      symbol: '005930.KS',
+      providers: ['dart', 'fred', 'finnhub'],
+      fredSeries: ['FEDFUNDS'],
+      now: new Date('2026-05-06T00:00:00Z')
+    });
+
+    const snapshot = report.analysis?.marketSnapshot;
+    expect(snapshot).toMatchObject({
+      schemaVersion: 'market-context-snapshot.v1',
+      subject: { company: '삼성전자', dartCorpCode: '00126380', symbol: '005930.KS' },
+      coverage: {
+        dart: { status: 'ok', filingsAnalyzed: 4, renderedFilings: 4, confidence: 'exact-corp-code' },
+        fred: { status: 'ok', seriesAnalyzed: 1 },
+        finnhub: { status: 'ok', hasProfile: true }
+      }
+    });
+    expect(snapshot?.bullCases.some((item) => item.evidence.some((evidence) => evidence.provider === 'dart' && evidence.receiptNo === '20260502000002'))).toBe(true);
+    expect(snapshot?.bearCases.some((item) => item.evidence.some((evidence) => evidence.provider === 'dart' && evidence.receiptNo === '20260504000004'))).toBe(true);
+    expect(snapshot?.risks.some((item) => item.evidence.some((evidence) => evidence.provider === 'dart' && evidence.receiptNo === '20260503000003'))).toBe(true);
+    expect(snapshot?.catalysts.some((item) => item.evidence.some((evidence) => evidence.provider === 'dart' && evidence.receiptNo === '20260501000001'))).toBe(true);
+    expect(snapshot?.risks.some((item) => item.evidence.some((evidence) => evidence.provider === 'fred' && evidence.seriesId === 'FEDFUNDS'))).toBe(true);
+    expect(snapshot?.bullCases.some((item) => item.evidence.some((evidence) => evidence.provider === 'finnhub' && evidence.symbol === '005930.KS'))).toBe(true);
+  });
+
+  it('renders the structured MarketContextSnapshot analysis report with provider evidence', async () => {
+    globalThis.fetch = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('opendart.fss.or.kr')) return new Response(JSON.stringify(dartList([{ corp_name: '삼성전자', rcept_no: '20260501000001', report_nm: '단일판매ㆍ공급계약체결', flr_nm: '삼성전자', rcept_dt: '20260501', rm: '' }])), { status: 200 });
+      if (url.includes('stlouisfed.org')) return new Response(JSON.stringify(fredObservations('5.25')), { status: 200 });
+      return new Response(JSON.stringify({ name: 'Samsung Electronics', ticker: '005930.KS', marketCapitalization: 450000 }), { status: 200 });
+    }) as never;
+
+    const report = await fetchExternalMarketContext({ company: '삼성전자', dartCorpCode: '00126380', symbol: '005930.KS', providers: ['dart', 'fred', 'finnhub'], fredSeries: ['FEDFUNDS'] });
+    const rendered = renderExternalMarketContextReport(report);
+
+    expect(rendered).toContain('### MarketContextSnapshot');
+    expect(rendered).toContain('**Bull case**');
+    expect(rendered).toContain('**Bear case**');
+    expect(rendered).toContain('**Risks**');
+    expect(rendered).toContain('**Catalysts**');
+    expect(rendered).toContain('DART: 단일판매ㆍ공급계약체결');
+    expect(rendered).toContain('FRED: FEDFUNDS');
+    expect(rendered).toContain('Finnhub: 005930.KS');
+  });
+
+  it('does not include analysis when includeSnapshot is false', async () => {
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify(dartList([])), { status: 200 })) as never;
+
+    const report = await fetchExternalMarketContext({ company: '삼성전자', dartCorpCode: '00126380', providers: ['dart'], includeSnapshot: false });
+
+    expect(report.analysis).toBeUndefined();
+    expect(renderExternalMarketContextReport(report)).not.toContain('MarketContextSnapshot');
+  });
+
+  it('redacts credential-bearing provider errors in JSON and Markdown', async () => {
+    globalThis.fetch = vi.fn(async () => {
+      throw new Error('failed URL https://opendart.fss.or.kr/api/list.json?crtfc_key=dk&corp_code=00126380');
+    }) as never;
+
+    const report = await fetchExternalMarketContext({ company: '삼성전자', dartCorpCode: '00126380', providers: ['dart'] });
+    const rendered = renderExternalMarketContextReport(report);
+
+    expect(rendered).toContain('[REDACTED]');
+    expect(rendered).not.toContain('dk');
+    expect(JSON.stringify(report)).not.toContain('dk');
+  });
+});

package/tests/core/fact-deriver.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+
+import { FactDeriver, makeEventDerivedFactId } from '../../src/core/derive/fact-deriver.js';
+import type { MemoryEvent } from '../../src/core/types.js';
+
+function makeEvent(overrides: Partial<MemoryEvent>): MemoryEvent {
+  return {
+    id: '11111111-1111-4111-8111-111111111111',
+    eventType: 'user_prompt',
+    sessionId: 'session-1',
+    timestamp: new Date('2026-04-30T00:00:00.000Z'),
+    content: 'default content',
+    canonicalKey: 'default-content',
+    dedupeKey: 'session-1:default-content',
+    ...overrides
+  };
+}
+
+describe('FactDeriver', () => {
+  it('derives a deterministic fact from a user prompt', () => {
+    const deriver = new FactDeriver();
+    const event = makeEvent({
+      content: 'We decided to keep SQLite as the canonical store.',
+      metadata: {
+        scope: { project: { hash: 'proj123' } },
+        tags: ['proj:proj123', 'architecture']
+      }
+    });
+
+    const facts = deriver.deriveFromEvent(event, { now: new Date('2026-04-30T01:02:03.000Z') });
+
+    expect(facts).toHaveLength(1);
+    expect(facts[0]).toMatchObject({
+      factId: makeEventDerivedFactId(event.id, 'decision'),
+      projectHash: 'proj123',
+      factType: 'decision',
+      text: 'User asked: We decided to keep SQLite as the canonical store.',
+      derivedFromEventIds: [event.id],
+      sourceKind: 'prompt',
+      confidence: 0.65,
+      importance: 0.5,
+      tags: ['proj:proj123', 'architecture'],
+      createdAt: '2026-04-30T01:02:03.000Z',
+      updatedAt: '2026-04-30T01:02:03.000Z'
+    });
+  });
+
+  it('derives tool observation facts with tool metadata', () => {
+    const deriver = new FactDeriver();
+    const event = makeEvent({
+      eventType: 'tool_observation',
+      content: '{"toolName":"terminal","success":false}',
+      metadata: {
+        toolName: 'terminal',
+        success: false,
+        fileRefs: ['src/services/memory-service.ts']
+      }
+    });
+
+    const [fact] = deriver.deriveFromEvent(event, {
+      projectHash: 'fallback-project',
+      now: new Date('2026-04-30T01:02:03.000Z')
+    });
+
+    expect(fact).toMatchObject({
+      factType: 'tool_observation',
+      projectHash: 'fallback-project',
+      sourceKind: 'tool',
+      text: 'Tool terminal failed: {"toolName":"terminal","success":false}',
+      fileRefs: ['src/services/memory-service.ts']
+    });
+  });
+
+  it('skips empty event content', () => {
+    const deriver = new FactDeriver();
+    const facts = deriver.deriveFromEvent(makeEvent({ content: '   ' }));
+    expect(facts).toEqual([]);
+  });
+});