Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.31 Phase 6 — facts engine round-trip tests on PGLite (in-memory, no
* DATABASE_URL required).
*
* Pins every BrainEngine facts method end-to-end:
* - insertFact (insert, supersede)
* - expireFact (idempotent-as-false)
* - listFactsByEntity / Since / Session / Supersessions
* - findCandidateDuplicates (entity-prefiltered, k cap, cosine ordering)
* - consolidateFact
* - getFactsHealth
*/
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { configureGateway, resetGateway } from '../src/core/ai/gateway.ts';
let engine: PGLiteEngine;
beforeAll(async () => {
// Pin the embedding dim to 1536 BEFORE initSchema. vec() hardcodes
// Float32Array(1536), but initSchema sizes vector columns from
// process-global gateway state (getEmbeddingDimensions(), default 1280).
// Whether this file passes therefore depends on which test files run
// before it in the shard; adding test files to the repo reshuffles the
// weight-packed shards, so unrelated PRs trip it ("expected 1280
// dimensions, not 1536"). Same fix + rationale as
// doctor-hidden-by-search-policy.test.ts (#2801),
// engine-find-trajectory.test.ts and cosine-rescore-column.test.ts.
resetGateway();
configureGateway({
embedding_model: 'openai:text-embedding-3-large',
embedding_dimensions: 1536,
env: { OPENAI_API_KEY: 'sk-test-facts-engine' },
});
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
});
afterAll(async () => {
await engine.disconnect();
resetGateway();
});
const vec = (...vals: number[]): Float32Array => {
const a = new Float32Array(1536);
for (let i = 0; i < vals.length; i++) a[i] = vals[i];
return a;
};
describe('insertFact + listFactsByEntity', () => {
test('inserts a fact and reads it back', async () => {
const r = await engine.insertFact(
{ fact: 'alice example fact', kind: 'fact', entity_slug: 'people/alice-example', source: 'test' },
{ source_id: 'default' },
);
expect(r.id).toBeGreaterThan(0);
expect(r.status).toBe('inserted');
const rows = await engine.listFactsByEntity('default', 'people/alice-example');
expect(rows.length).toBeGreaterThanOrEqual(1);
const ours = rows.find(x => x.id === r.id);
expect(ours).toBeDefined();
expect(ours!.fact).toBe('alice example fact');
expect(ours!.kind).toBe('fact');
expect(ours!.visibility).toBe('private');
// v0.31.2: row mapper exposes notability; default 'medium' when caller omits.
expect(ours!.notability).toBe('medium');
expect(ours!.confidence).toBe(1.0);
});
test('unconsolidatedOnly excludes active facts with consolidated_at set', async () => {
const entitySlug = 'people/consolidation-filter-example';
const consolidated = await engine.insertFact(
{ fact: 'already consolidated', kind: 'fact', entity_slug: entitySlug, source: 'test' },
{ source_id: 'default' },
);
const pending = await engine.insertFact(
{ fact: 'still pending', kind: 'fact', entity_slug: entitySlug, source: 'test' },
{ source_id: 'default' },
);
await engine.executeRaw(
`UPDATE facts SET consolidated_at = now() WHERE id = $1`,
[consolidated.id],
);
const active = await engine.listFactsByEntity('default', entitySlug);
const unconsolidated = await engine.listFactsByEntity('default', entitySlug, {
unconsolidatedOnly: true,
});
expect(new Set(active.map(f => f.id))).toEqual(new Set([consolidated.id, pending.id]));
expect(unconsolidated.map(f => f.id)).toEqual([pending.id]);
});
test('respects kind CHECK', async () => {
const r = await engine.insertFact(
{ fact: 'durable', kind: 'preference', entity_slug: 'alice-test', source: 'test' },
{ source_id: 'default' },
);
const rows = await engine.listFactsByEntity('default', 'alice-test');
const ours = rows.find(x => x.id === r.id);
expect(ours?.kind).toBe('preference');
});
test('v0.31.2: notability round-trips for each tier (PR1 commit 4 contract pin)', async () => {
const tiers: Array<'high' | 'medium' | 'low'> = ['high', 'medium', 'low'];
for (const tier of tiers) {
const r = await engine.insertFact(
{
fact: `notability ${tier} test`,
kind: 'fact',
entity_slug: `notability-${tier}-pin`,
source: 'test',
notability: tier,
},
{ source_id: 'default' },
);
const rows = await engine.listFactsByEntity('default', `notability-${tier}-pin`);
const ours = rows.find(x => x.id === r.id);
expect(ours).toBeDefined();
// The row mapper MUST expose notability; without this assertion, the
// codex P1 #4 regression (FactRow drops the column) reappears silently.
expect(ours!.notability).toBe(tier);
}
});
test('supersede path: superseding row marks old as expired_at + superseded_by', async () => {
const old = await engine.insertFact(
{ fact: 'old fact', kind: 'fact', entity_slug: 'super-test', source: 'test' },
{ source_id: 'default' },
);
const newer = await engine.insertFact(
{ fact: 'new fact', kind: 'fact', entity_slug: 'super-test', source: 'test' },
{ source_id: 'default', supersedeId: old.id },
);
expect(newer.status).toBe('superseded');
expect(newer.id).toBeGreaterThan(old.id);
const supersessions = await engine.listSupersessions('default');
const oldRow = supersessions.find(r => r.id === old.id);
expect(oldRow).toBeDefined();
expect(oldRow!.expired_at).not.toBeNull();
expect(oldRow!.superseded_by).toBe(newer.id);
});
});
describe('expireFact', () => {
test('returns true on first call, false on idempotent re-call', async () => {
const r = await engine.insertFact(
{ fact: 'will expire', kind: 'fact', source: 'test' },
{ source_id: 'default' },
);
expect(await engine.expireFact(r.id)).toBe(true);
expect(await engine.expireFact(r.id)).toBe(false);
});
test('returns false on unknown id', async () => {
expect(await engine.expireFact(99999999)).toBe(false);
});
});
describe('listFactsSince + listFactsBySession', () => {
test('listFactsSince filters by created_at', async () => {
const before = new Date();
await engine.insertFact(
{ fact: 'recent', kind: 'fact', source: 'test', source_session: 'topic-since' },
{ source_id: 'default' },
);
const rows = await engine.listFactsSince('default', before);
expect(rows.length).toBeGreaterThanOrEqual(1);
expect(rows.every(r => r.created_at.getTime() >= before.getTime())).toBe(true);
});
test('listFactsBySession filters by source_session', async () => {
await engine.insertFact(
{ fact: 'topic-A note', kind: 'fact', source: 'test', source_session: 'topic-A' },
{ source_id: 'default' },
);
await engine.insertFact(
{ fact: 'topic-B note', kind: 'fact', source: 'test', source_session: 'topic-B' },
{ source_id: 'default' },
);
const a = await engine.listFactsBySession('default', 'topic-A');
const b = await engine.listFactsBySession('default', 'topic-B');
expect(a.every(r => r.source_session === 'topic-A')).toBe(true);
expect(b.every(r => r.source_session === 'topic-B')).toBe(true);
expect(a.find(r => r.source_session === 'topic-B')).toBeUndefined();
});
});
describe('listFactsSince eventTime option', () => {
// Simulates a batch backfill (e.g. extract-conversation-facts run over
// many pages at once): rows land with created_at clustered around the
// batch's run time, but valid_from records when the underlying event
// actually happened. Without eventTime, "what happened yesterday"
// recall sorts/filters by extraction order instead of event date.
test('default (eventTime unset) filters/orders by created_at, ignoring valid_from', async () => {
const slug = `evt-default-${Math.random().toString(36).slice(2, 8)}`;
const eventOld = new Date(Date.now() - 10 * 24 * 60 * 60 * 1000); // event: 10 days ago
const eventRecent = new Date(Date.now() - 60 * 60 * 1000); // event: 1 hour ago
await engine.insertFact(
{ fact: `${slug} old-event`, kind: 'fact', entity_slug: slug, source: 'test', valid_from: eventOld },
{ source_id: 'default' },
);
await engine.insertFact(
{ fact: `${slug} recent-event`, kind: 'fact', entity_slug: slug, source: 'test', valid_from: eventRecent },
{ source_id: 'default' },
);
const since48h = new Date(Date.now() - 48 * 60 * 60 * 1000);
// Both rows were just created_at=now() by this test (regardless of
// their backdated valid_from), so both pass a 48h created_at window —
// this is the bug: a 10-day-old event still shows up in "last 48h".
const rows = await engine.listFactsSince('default', since48h, { entitySlug: slug });
expect(rows.length).toBe(2);
});
test('eventTime:true filters by valid_from — a backdated event drops out of a 48h window', async () => {
const slug = `evt-filter-${Math.random().toString(36).slice(2, 8)}`;
const eventOld = new Date(Date.now() - 10 * 24 * 60 * 60 * 1000);
const eventRecent = new Date(Date.now() - 60 * 60 * 1000);
await engine.insertFact(
{ fact: `${slug} old-event`, kind: 'fact', entity_slug: slug, source: 'test', valid_from: eventOld },
{ source_id: 'default' },
);
await engine.insertFact(
{ fact: `${slug} recent-event`, kind: 'fact', entity_slug: slug, source: 'test', valid_from: eventRecent },
{ source_id: 'default' },
);
const since48h = new Date(Date.now() - 48 * 60 * 60 * 1000);
const rows = await engine.listFactsSince('default', since48h, { entitySlug: slug, eventTime: true });
expect(rows.length).toBe(1);
expect(rows[0].fact).toBe(`${slug} recent-event`);
});
test('eventTime:true orders by valid_from DESC instead of created_at DESC', async () => {
const slug = `evt-order-${Math.random().toString(36).slice(2, 8)}`;
// Insert the LATER event FIRST (earlier created_at), then the EARLIER
// event SECOND (later created_at) — created_at-order and valid_from-order
// now disagree, so the ordering switch is directly observable.
const laterEvent = new Date(Date.now() - 60 * 60 * 1000); // 1h ago
const earlierEvent = new Date(Date.now() - 5 * 60 * 60 * 1000); // 5h ago
await engine.insertFact(
{
fact: `${slug} later-event-inserted-first`,
kind: 'fact',
entity_slug: slug,
source: 'test',
valid_from: laterEvent,
},
{ source_id: 'default' },
);
await engine.insertFact(
{
fact: `${slug} earlier-event-inserted-second`,
kind: 'fact',
entity_slug: slug,
source: 'test',
valid_from: earlierEvent,
},
{ source_id: 'default' },
);
const since = new Date(0);
const byCreated = await engine.listFactsSince('default', since, { entitySlug: slug });
const byEvent = await engine.listFactsSince('default', since, { entitySlug: slug, eventTime: true });
expect(byCreated.length).toBe(2);
expect(byEvent.length).toBe(2);
// default: created_at DESC -> the row inserted second (later created_at) is first
expect(byCreated[0].fact).toBe(`${slug} earlier-event-inserted-second`);
// eventTime: valid_from DESC -> the row with the later event date is first
expect(byEvent[0].fact).toBe(`${slug} later-event-inserted-first`);
});
});
describe('findCandidateDuplicates', () => {
test('entity-prefiltered: rows from other entities never returned', async () => {
await engine.insertFact(
{ fact: 'alice fact', kind: 'fact', entity_slug: 'cand-alice', source: 'test' },
{ source_id: 'default' },
);
await engine.insertFact(
{ fact: 'tim fact', kind: 'fact', entity_slug: 'cand-tim', source: 'test' },
{ source_id: 'default' },
);
const candidates = await engine.findCandidateDuplicates('default', 'cand-alice', 'alice fact');
expect(candidates.every(c => c.entity_slug === 'cand-alice')).toBe(true);
expect(candidates.find(c => c.entity_slug === 'cand-tim')).toBeUndefined();
});
test('k cap honored', async () => {
for (let i = 0; i < 7; i++) {
await engine.insertFact(
{ fact: `cap-test ${i}`, kind: 'fact', entity_slug: 'cap-entity', source: 'test' },
{ source_id: 'default' },
);
}
const result = await engine.findCandidateDuplicates('default', 'cap-entity', 'x', { k: 3 });
expect(result.length).toBe(3);
});
test('embedding cosine ordering when both sides have embeddings', async () => {
// Use per-run unique entity_slug so the assertion is immune to any
// cross-test pollution (no other test in the file uses 'embed-test',
// but parallel CI shard runs have surfaced a flake where the
// position-0 assertion failed without a visible assertion-detail in
// the truncated log). The contract this test pins is "A ranks higher
// than B because cos(A,query)=1.0 vs cos(B,query)=0.0" — assert that
// RELATIONSHIP, not the absolute index, so any unrelated row in the
// result set can't flip the test.
const slug = `embed-test-${Math.random().toString(36).slice(2, 10)}`;
await engine.insertFact(
{ fact: 'A', kind: 'fact', entity_slug: slug, source: 'test', embedding: vec(1, 0, 0), embedding_model: 'synthetic:model' },
{ source_id: 'default' },
);
await engine.insertFact(
{ fact: 'B', kind: 'fact', entity_slug: slug, source: 'test', embedding: vec(0, 1, 0), embedding_model: 'synthetic:model' },
{ source_id: 'default' },
);
const result = await engine.findCandidateDuplicates(
'default', slug, 'q',
{ embedding: vec(1, 0, 0), embeddingModel: 'synthetic:model' },
);
const aIdx = result.findIndex(r => r.fact === 'A');
const bIdx = result.findIndex(r => r.fact === 'B');
expect(aIdx).toBeGreaterThanOrEqual(0); // A is in the result
expect(bIdx).toBeGreaterThanOrEqual(0); // B is in the result
// Closest by cosine MUST come first.
expect(aIdx).toBeLessThan(bIdx);
});
});
describe('consolidateFact', () => {
test('marks consolidated_at + consolidated_into; never DELETE', async () => {
// Need a take to point at — seed a page + take.
await engine.executeRaw(
`INSERT INTO pages (slug, type, title) VALUES ('cons-test', 'concept', 'Cons Test') ON CONFLICT DO NOTHING`,
);
const pageRows = await engine.executeRaw<{ id: number }>(
`SELECT id FROM pages WHERE slug = 'cons-test' AND source_id = 'default'`,
);
const pageId = pageRows[0].id;
await engine.executeRaw(
`INSERT INTO takes (page_id, row_num, claim, kind, holder) VALUES ($1, 99, 'cons claim', 'fact', 'self') ON CONFLICT DO NOTHING`,
[pageId],
);
const takeRows = await engine.executeRaw<{ id: number }>(
`SELECT id FROM takes WHERE page_id = $1 AND row_num = 99`,
[pageId],
);
const takeId = takeRows[0].id;
const fact = await engine.insertFact(
{ fact: 'will be consolidated', kind: 'fact', entity_slug: 'cons-test', source: 'test' },
{ source_id: 'default' },
);
await engine.consolidateFact(fact.id, takeId);
const rows = await engine.executeRaw<{ id: number; consolidated_at: Date | null; consolidated_into: number | null }>(
`SELECT id, consolidated_at, consolidated_into FROM facts WHERE id = $1`,
[fact.id],
);
expect(rows.length).toBe(1);
expect(rows[0].consolidated_at).not.toBeNull();
expect(Number(rows[0].consolidated_into)).toBe(takeId);
});
});
describe('getFactsHealth', () => {
test('returns counters keyed by source_id', async () => {
const health = await engine.getFactsHealth('default');
expect(health.source_id).toBe('default');
expect(health.total_active).toBeGreaterThanOrEqual(0);
expect(health.total_today).toBeGreaterThanOrEqual(0);
expect(health.total_week).toBeGreaterThanOrEqual(0);
expect(Array.isArray(health.top_entities)).toBe(true);
});
test('total_today subset of total_week subset of total_active+expired', async () => {
const health = await engine.getFactsHealth('default');
expect(health.total_today).toBeLessThanOrEqual(health.total_week);
expect(health.total_active + health.total_expired).toBeGreaterThanOrEqual(health.total_week);
});
});