Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #4222 — generic-token entity junk guards.
*
* Three seams share one reject list (src/core/entity-name-quality.ts):
* 1. enrichEntity refuses to MINT a page for a single generic token or a
* bare @handle (existing pages stay trusted — update path unaffected).
* 2. buildGazetteer drops single-generic-token titles of every page type
* (#6958; person-only before) so an already-minted junk page stops
* accreting mention edges.
* 3. The junk_entity_hubs doctor check surfaces near-empty pages with
* huge edge counts (warn + list, never auto-delete).
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import {
GENERIC_ENTITY_TOKENS,
isGenericEntityToken,
isJunkEntityName,
} from '../src/core/entity-name-quality.ts';
import { enrichEntity } from '../src/core/enrichment-service.ts';
import { buildGazetteer, type DroppedName } from '../src/core/by-mention.ts';
import {
checkJunkEntityHubs,
JUNK_HUB_EDGE_THRESHOLD,
JUNK_HUB_MAX_CHUNKS,
} from '../src/commands/doctor/checks/graph-embedding.ts';
import type { LinkBatchInput } from '../src/core/engine.ts';
let engine: PGLiteEngine;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
}, 120_000);
afterAll(async () => {
if (engine) await engine.disconnect();
}, 60_000);
async function truncateAll() {
for (const t of ['content_chunks', 'links', 'tags', 'timeline_entries', 'page_versions', 'ingest_log', 'pages']) {
await (engine as unknown as { db: { exec(q: string): Promise<unknown> } }).db.exec(`DELETE FROM ${t}`);
}
}
// ── 1. Shared reject list ───────────────────────────────────────────────
describe('entity-name-quality (#4222)', () => {
test('the observed junk-hub tokens are all on the list', () => {
for (const t of ['will', 'something', 'info', 'chief', 'unknown', 'readme', 'founders']) {
expect(GENERIC_ENTITY_TOKENS.has(t)).toBe(true);
expect(isGenericEntityToken(t)).toBe(true);
}
});
test('matching is case-insensitive', () => {
expect(isGenericEntityToken('Will')).toBe(true);
expect(isGenericEntityToken('CHIEF')).toBe(true);
});
test('isJunkEntityName: single generic token or bare @handle', () => {
expect(isJunkEntityName('Will')).toBe(true);
expect(isJunkEntityName('info')).toBe(true);
expect(isJunkEntityName('@alice_dev')).toBe(true);
expect(isJunkEntityName('@AcmeCorp')).toBe(true);
expect(isJunkEntityName(' ')).toBe(true);
});
test('isJunkEntityName: multi-word names and real names always pass', () => {
expect(isJunkEntityName('Will Smith')).toBe(false);
expect(isJunkEntityName('Alice Chen')).toBe(false);
expect(isJunkEntityName('Acme')).toBe(false); // single but NOT generic
expect(isJunkEntityName('Info Systems Inc')).toBe(false);
});
});
// ── 2. enrichEntity mint gate ───────────────────────────────────────────
describe('enrichEntity mint gate (#4222)', () => {
beforeEach(truncateAll);
test('single generic token is skipped — no page minted', async () => {
const result = await enrichEntity(engine, {
entityName: 'Will',
entityType: 'person',
context: 'Will follow up next week',
sourceSlug: 'meetings/standup',
}, { trusted: true });
expect(result.action).toBe('skipped');
expect(await engine.getPage('people/will')).toBeNull();
});
test('bare @handle is skipped — no page minted', async () => {
const result = await enrichEntity(engine, {
entityName: '@alice_dev',
entityType: 'person',
context: 'mentioned by @alice_dev',
sourceSlug: 'meetings/standup',
}, { trusted: true });
expect(result.action).toBe('skipped');
expect(await engine.getPage('people/alice-dev')).toBeNull();
});
test('an EXISTING page with a generic title stays trusted (update path)', async () => {
await engine.putPage('people/will', {
type: 'person', title: 'Will', compiled_truth: 'A real person the user created.', timeline: '',
});
const result = await enrichEntity(engine, {
entityName: 'Will',
entityType: 'person',
context: 'update for existing page',
sourceSlug: 'meetings/standup',
}, { trusted: true });
expect(result.action).toBe('updated');
});
test('multi-word names still mint', async () => {
const result = await enrichEntity(engine, {
entityName: 'Will Smith',
entityType: 'person',
context: 'met Will Smith',
sourceSlug: 'meetings/standup',
}, { trusted: true });
expect(result.action).toBe('created');
expect(await engine.getPage('people/will-smith')).not.toBeNull();
});
});
// ── 3. buildGazetteer drop ──────────────────────────────────────────────
describe('buildGazetteer generic-title drop (#4222, #6958)', () => {
beforeEach(truncateAll);
test('single-generic-token titles are dropped for every type; multi-token titles kept', async () => {
await engine.putPage('people/will', {
type: 'person', title: 'Will', compiled_truth: 'junk hub magnet', timeline: '',
});
await engine.putPage('people/will-smith', {
type: 'person', title: 'Will Smith', compiled_truth: 'a real person', timeline: '',
});
// #6958: the gate is no longer person-only.
await engine.putPage('companies/info', {
type: 'company', title: 'Info', compiled_truth: 'a company', timeline: '',
});
await engine.putPage('companies/info-labs-example', {
type: 'company', title: 'Info Labs Example', compiled_truth: 'a real company', timeline: '',
});
const dropped: DroppedName[] = [];
const gazetteer = await buildGazetteer(engine, { dropped });
const willBucket = gazetteer.get('will') ?? [];
expect(willBucket.some(e => e.slug === 'people/will')).toBe(false);
expect(willBucket.some(e => e.slug === 'people/will-smith')).toBe(true);
const infoBucket = gazetteer.get('info') ?? [];
expect(infoBucket.some(e => e.slug === 'companies/info')).toBe(false);
expect(infoBucket.some(e => e.slug === 'companies/info-labs-example')).toBe(true);
expect(dropped.filter(d => d.reason === 'generic_token').map(d => d.slug).sort())
.toEqual(['companies/info', 'people/will']);
});
});
// ── 4. junk_entity_hubs doctor check ────────────────────────────────────
describe('junk_entity_hubs doctor check (#4222)', () => {
beforeEach(truncateAll);
test('shipped thresholds are the documented ones', () => {
expect(JUNK_HUB_EDGE_THRESHOLD).toBe(1000);
expect(JUNK_HUB_MAX_CHUNKS).toBe(2);
});
test('warns and lists near-empty pages with edge counts over threshold', async () => {
await engine.putPage('people/will', {
type: 'person', title: 'Will', compiled_truth: 'stub', timeline: '',
});
const batch: LinkBatchInput[] = [];
for (let i = 0; i < 4; i++) {
const slug = `notes/n-${i}`;
await engine.putPage(slug, { type: 'note', title: `Note ${i}`, compiled_truth: 'body', timeline: '' });
batch.push({ from_slug: slug, to_slug: 'people/will', link_source: 'mentions' });
}
await engine.addLinksBatch(batch);
// Threshold overridden for test-scale corpus; production uses defaults.
const check = await checkJunkEntityHubs(engine, { edgeThreshold: 3, maxChunks: 2 });
expect(check.name).toBe('junk_entity_hubs');
expect(check.status).toBe('warn');
expect(check.message).toContain('people/will');
const hubs = (check.details as { hubs: Array<{ slug: string; edges: number }> }).hubs;
expect(hubs.some(h => h.slug === 'people/will' && h.edges >= 4)).toBe(true);
// The note pages have few edges — not listed.
expect(hubs.some(h => h.slug.startsWith('notes/'))).toBe(false);
});
test('content-rich pages are exempt even with many edges', async () => {
await engine.putPage('people/notable', {
type: 'person', title: 'Notable Person', compiled_truth: 'real content', timeline: '',
});
await engine.upsertChunks('people/notable', [0, 1, 2].map(i => ({
chunk_index: i, chunk_text: `chunk ${i}`, chunk_source: 'compiled_truth' as const, token_count: 2,
})));
const batch: LinkBatchInput[] = [];
for (let i = 0; i < 4; i++) {
const slug = `notes/m-${i}`;
await engine.putPage(slug, { type: 'note', title: `M ${i}`, compiled_truth: 'body', timeline: '' });
batch.push({ from_slug: slug, to_slug: 'people/notable', link_source: 'mentions' });
}
await engine.addLinksBatch(batch);
const check = await checkJunkEntityHubs(engine, { edgeThreshold: 3, maxChunks: 2 });
expect(check.status).toBe('ok');
});
test('ok on an empty brain', async () => {
const check = await checkJunkEntityHubs(engine);
expect(check.status).toBe('ok');
});
test('junk_hub_exempt: true opts an intentional thin hub page out', async () => {
await engine.putPage('topic/misc', {
type: 'concept',
title: 'misc — topic hub (auto-created for graph wiring). Groups its member pages.',
compiled_truth: 'stub',
timeline: '',
frontmatter: { junk_hub_exempt: true, junk_hub_exempt_reason: 'intentional topic-organization scaffolding' },
});
const batch: LinkBatchInput[] = [];
for (let i = 0; i < 4; i++) {
const slug = `notes/e-${i}`;
await engine.putPage(slug, { type: 'note', title: `Note ${i}`, compiled_truth: 'body', timeline: '' });
batch.push({ from_slug: slug, to_slug: 'topic/misc', link_source: 'mentions' });
}
await engine.addLinksBatch(batch);
const check = await checkJunkEntityHubs(engine, { edgeThreshold: 3, maxChunks: 2 });
// Same shape as the junk-hub case above (few chunks, edges over threshold) —
// opted out, so it must not appear at all, and with nothing else in the
// corpus the check reports ok.
expect(check.status).toBe('ok');
if (check.details) {
const hubs = (check.details as { hubs: Array<{ slug: string }> }).hubs;
expect(hubs.some(h => h.slug === 'topic/misc')).toBe(false);
}
});
test('a page with the same shape but no exempt marker is still caught (regression control)', async () => {
await engine.putPage('topic/unmarked', {
type: 'concept', title: 'unmarked hub', compiled_truth: 'stub', timeline: '',
});
const batch: LinkBatchInput[] = [];
for (let i = 0; i < 4; i++) {
const slug = `notes/u-${i}`;
await engine.putPage(slug, { type: 'note', title: `Note ${i}`, compiled_truth: 'body', timeline: '' });
batch.push({ from_slug: slug, to_slug: 'topic/unmarked', link_source: 'mentions' });
}
await engine.addLinksBatch(batch);
const check = await checkJunkEntityHubs(engine, { edgeThreshold: 3, maxChunks: 2 });
expect(check.status).toBe('warn');
const hubs = (check.details as { hubs: Array<{ slug: string }> }).hubs;
expect(hubs.some(h => h.slug === 'topic/unmarked')).toBe(true);
});
test.each([
['boolean false', false],
['string "false"', 'false'],
['unrelated string', 'nope'],
])('junk_hub_exempt: %s does NOT opt the page out', async (_label, value) => {
const slug = `topic/not-exempt-${String(value).replace(/[^a-z0-9]/gi, '')}`;
await engine.putPage(slug, {
type: 'concept', title: 'not actually exempt', compiled_truth: 'stub', timeline: '',
frontmatter: { junk_hub_exempt: value },
});
const batch: LinkBatchInput[] = [];
for (let i = 0; i < 4; i++) {
const noteSlug = `notes/${slug.replace('topic/', '')}-${i}`;
await engine.putPage(noteSlug, { type: 'note', title: `Note ${i}`, compiled_truth: 'body', timeline: '' });
batch.push({ from_slug: noteSlug, to_slug: slug, link_source: 'mentions' });
}
await engine.addLinksBatch(batch);
const check = await checkJunkEntityHubs(engine, { edgeThreshold: 3, maxChunks: 2 });
expect(check.status).toBe('warn');
const hubs = (check.details as { hubs: Array<{ slug: string }> }).hubs;
expect(hubs.some(h => h.slug === slug)).toBe(true);
});
test('junk_hub_exempt: "true" (string, not boolean) DOES opt the page out', async () => {
await engine.putPage('topic/string-true-marked', {
type: 'concept', title: 'string-true marked hub', compiled_truth: 'stub', timeline: '',
frontmatter: { junk_hub_exempt: 'true' },
});
const batch: LinkBatchInput[] = [];
for (let i = 0; i < 4; i++) {
const noteSlug = `notes/st-${i}`;
await engine.putPage(noteSlug, { type: 'note', title: `Note ${i}`, compiled_truth: 'body', timeline: '' });
batch.push({ from_slug: noteSlug, to_slug: 'topic/string-true-marked', link_source: 'mentions' });
}
await engine.addLinksBatch(batch);
const check = await checkJunkEntityHubs(engine, { edgeThreshold: 3, maxChunks: 2 });
expect(check.status).toBe('ok');
if (check.details) {
const hubs = (check.details as { hubs: Array<{ slug: string }> }).hubs;
expect(hubs.some(h => h.slug === 'topic/string-true-marked')).toBe(false);
}
});
});
// #6158: a connector's own contact page collects its source's mention links by design
// (own-source twin first). Doctor must not call it an extractor-minted junk entity or offer
// junk_hub_exempt (the connector re-renders the page), and must name the main-brain twin.
describe('junk_entity_hubs connector contact pages (#6158)', () => {
beforeEach(truncateAll);
test('a connector contact page is reported as a connector twin, not a generic-token entity', async () => {
await engine.executeRaw(`INSERT INTO sources (id, name, config) VALUES ('google-example', 'google-example', '{"kind":"google"}'::jsonb) ON CONFLICT (id) DO NOTHING`);
await engine.putPage('people/alice-example', { type: 'person', title: 'Alice Example', compiled_truth: 'stub', timeline: '' });
await engine.putPage('people/alice-example', { type: 'person', title: 'Alice Example', compiled_truth: 'stub', timeline: '',
frontmatter: { google_contact_id: 'c123' } }, { sourceId: 'google-example' });
const batch: LinkBatchInput[] = [];
for (let i = 0; i < 4; i++) {
const slug = `mail/thread-${i}`;
await engine.putPage(slug, { type: 'note', title: `Thread ${i}`, compiled_truth: 'body', timeline: '' }, { sourceId: 'google-example' });
batch.push({ from_slug: slug, to_slug: 'people/alice-example', link_source: 'mentions', from_source_id: 'google-example', to_source_id: 'google-example' } as LinkBatchInput);
}
await engine.addLinksBatch(batch);
const check = await checkJunkEntityHubs(engine, { edgeThreshold: 3, maxChunks: 2 });
expect(check.status).toBe('warn');
expect(check.message).not.toContain('generic-token');
expect(check.message).not.toContain('junk_hub_exempt');
expect(check.message).toContain('people/alice-example [google-example]');
// W14 P4.5: real remedies instead of "open policy question": cross_source makes the stub yield to its twin.
expect(check.message).not.toContain('open policy question');
expect(check.message).toContain('link_resolution.cross_source true');
expect(check.message).toContain('--contacts-dir');
expect((check as { fix_unavailable_reason?: string }).fix_unavailable_reason).toBeUndefined();
expect((check as { fix?: { argv: string[] } }).fix?.argv).toEqual(['gbrain', 'config', 'set', 'link_resolution.cross_source', 'true']);
const details = check.details as { hubs: unknown[]; connector_twins: Array<Record<string, unknown>> };
expect(details.hubs).toEqual([]);
expect(details.connector_twins).toEqual([expect.objectContaining({ slug: 'people/alice-example', source_id: 'google-example',
canonical_twin: 'people/alice-example', canonical_twin_source: 'default' })]);
// With cross_source already on, the next step is the mention pass itself.
await engine.setConfig('link_resolution.cross_source', 'true');
try {
const on = await checkJunkEntityHubs(engine, { edgeThreshold: 3, maxChunks: 2 });
expect((on as { fix?: { argv: string[] } }).fix?.argv).toEqual(['gbrain', 'extract', '--stale']);
expect(on.message).toContain('extract --stale');
} finally {
await engine.setConfig('link_resolution.cross_source', 'false');
}
});
});