Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.8 KB
Raw Blame
/**
 * Entity mention index, version-aware coverage and invalidation
 * (mentions/coverage.ts, mentions/pass.ts, mentions/upgrade-notice.ts) on
 * PGLite.
 *
 * Protects: a binary whose MENTION_EXTRACTOR_VERSION or
 * ALIAS_DERIVATION_VERSION is ahead of the stored page state reports every
 * version-behind page as pending on an unchanged brain (whatever its
 * updated_at), on the card, get_backlinks and post-upgrade, until the sweep
 * finishes; the recount happens once and later coverage reads stay O(1);
 * an interrupted (deadline) sweep leaves an exact remaining count and the
 * next sweep finishes it; one cycle-budget sweep on a brain built at the
 * previous versions derives the new grammar's aliases and links; alias
 * staleness counts only linkable entity pages; changing
 * mentions.alias_deny, mentions.multiword_aliases or mentions.sibling_merge
 * marks pages due on an indexed brain; a denied alias comes back when the
 * deny is removed. Regression: coverage that reads `complete` after an
 * upgrade because no page was written since the last count.
 */
import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import type { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import {
  ALIAS_DERIVATION_VERSION, INDEX_VERSION_STAMP, MENTION_EXTRACTOR_VERSION, countMentionDuePages, runMentionPass,
} from '../src/core/mentions/pass.ts';
import { mentionCoverageNotice, readMentionCoverage } from '../src/core/mentions/coverage.ts';
import { mentionIndexUpgradeNotice } from '../src/core/mentions/upgrade-notice.ts';
import { deriveEntityAliases } from '../src/core/mentions/aliases.ts';
import { CYCLE_STALE_DRAIN_BUDGET_MS } from '../src/core/cycle.ts';
import { derivedAliases, mentionBrain, mentionLinks, page, resetMentionBrain, sweep } from './helpers/mention-brain.ts';

let engine: PGLiteEngine;
const config = { engine: 'pglite' } as never;
const remote = { remote: true, transport: 'stdio' as const, sourceId: 'default', takesHoldersAllowList: ['world'], config };

beforeAll(async () => { engine = await mentionBrain(); }, 120_000);
afterAll(async () => { await engine.disconnect(); });
beforeEach(async () => { await resetMentionBrain(engine); });

async function call(op: string, args: Record<string, unknown>) {
  const r = await dispatchToolCall(engine, op, args, remote as never);
  return { json: r.isError ? null : JSON.parse(r.content[0].text), notices: r.content.slice(1).map(c => c.text) };
}

const ACCOUNT_BODY = 'Account code: QUCO\nInternal nickname: Copper Fox\nOwner: Dana Example';
const account = () => page(engine, 'crm/123', 'crm', 'CRM record: Quormiro Capital', ACCOUNT_BODY);

/**
 * The page state and status row the previous binary left: page versions one
 * behind, and a status row counted without this binary's version stamp
 * (`aliasOnly`: only the alias version behind, stamped with it).
 */
async function asPreviousRelease(opts: { aliasOnly?: boolean } = {}) {
  if (!opts.aliasOnly) await engine.executeRaw('UPDATE page_mention_state SET mention_version = $1', [MENTION_EXTRACTOR_VERSION - 1]);
  await engine.executeRaw('UPDATE page_mention_state SET alias_version = $1 WHERE alias_version IS NOT NULL', [ALIAS_DERIVATION_VERSION - 1]);
  await engine.executeRaw(
    `UPDATE mention_index_status SET policy_fingerprint = split_part(policy_fingerprint, ';', 1) || $1`,
    [opts.aliasOnly ? `;v${MENTION_EXTRACTOR_VERSION}.${ALIAS_DERIVATION_VERSION - 1}` : '']);
}

async function statusRow() {
  const [row] = await engine.executeRaw<{ state: string; pending: number; policy_fingerprint: string | null }>(
    "SELECT state, pending, policy_fingerprint FROM mention_index_status WHERE source_id = 'default'");
  return row!;
}

/** Wraps `engine` so every SQL statement it runs is recorded. */
function recording(target: BrainEngine, sqls: string[]): BrainEngine {
  return new Proxy(target, {
    get(t, key) {
      if (key === 'executeRaw') return (sql: string, params?: unknown[]) => { sqls.push(sql); return t.executeRaw(sql, params as never); };
      const value = Reflect.get(t, key, t);
      return typeof value === 'function' ? value.bind(t) : value;
    },
  });
}

describe('coverage after a version bump on an unchanged brain', () => {
  test('every version-behind page is pending at once; card, get_backlinks and post-upgrade carry it until the sweep finishes', async () => {
    await account();
    await page(engine, 'companies/acme', 'company', 'Acme Example', 'A company.');
    for (let i = 0; i < 4; i++) await page(engine, `tickets/t${i}`, 'ticket', `Ticket ${i}`, 'Customer: QUCO');
    await sweep(engine);
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'complete', pending_pages: 0 });
    const linksBefore = await mentionLinks(engine);

    await asPreviousRelease();
    const [written] = await engine.executeRaw<{ n: number }>(
      "SELECT count(*)::int AS n FROM pages p, mention_index_status m WHERE m.source_id = 'default' AND p.updated_at >= m.counted_at");
    expect(written!.n).toBe(0);

    const coverage = await readMentionCoverage(engine, ['default']);
    expect(coverage).toMatchObject({ state: 'pending', pending_pages: 6, degraded: true });
    expect(mentionCoverageNotice(coverage)?.fix?.argv).toEqual(['gbrain', 'extract', '--stale', '--catch-up']);
    // The recount is saved once on the status row with this binary's stamp.
    expect(await statusRow()).toMatchObject({ state: 'pending', pending: 6 });
    expect((await statusRow()).policy_fingerprint).toEndWith(`;${INDEX_VERSION_STAMP}`);
    const sqls: string[] = [];
    expect(await readMentionCoverage(recording(engine, sqls), ['default'])).toMatchObject({ state: 'pending', pending_pages: 6 });
    expect(sqls.some(s => s.includes('alias_version'))).toBe(false);

    const card = await call('entity', { name: 'QUCO' });
    expect(card.json.card.coverage).toMatchObject({ state: 'pending', pending_pages: 6, degraded: true });
    expect(card.notices.join('\n')).toContain('[gbrain notice mention_index');
    const backlinks = await call('get_backlinks', { slug: 'crm/123', group: 'page' });
    expect(backlinks.json.coverage).toMatchObject({ state: 'pending', pending_pages: 6 });
    expect(backlinks.notices.join('\n')).toContain('[gbrain notice mention_index');
    const notice = (await mentionIndexUpgradeNotice(engine))?.join('\n') ?? '';
    expect(notice).toContain('[AGENT]');
    expect(notice).toContain('gbrain extract --stale --catch-up');
    expect(notice).toContain('6 page(s)');

    await sweep(engine);
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'complete', pending_pages: 0 });
    expect(await statusRow()).toMatchObject({ state: 'complete', pending: 0 });
    expect(await mentionLinks(engine)).toEqual(linksBefore);
    expect(await mentionIndexUpgradeNotice(engine)).toBeNull();
    expect((await call('entity', { name: 'QUCO' })).notices.join('\n')).not.toContain('mention_index');
  });

  test('an interrupted sweep (deadline) leaves the exact remaining count; the next sweep finishes it', async () => {
    await account();
    for (let i = 0; i < 450; i++) await page(engine, `mail/m${i}`, 'email', `Mail ${i}`, i % 50 === 0 ? 'Re: QUCO renewal' : 'Weekly digest');
    await sweep(engine);
    const linksBefore = await mentionLinks(engine);
    expect(linksBefore.length).toBe(9);
    await asPreviousRelease();

    const realNow = Date.now;
    let during: Awaited<ReturnType<typeof readMentionCoverage>> | null = null;
    let interrupted;
    try {
      interrupted = await runMentionPass(engine, {
        deadline: realNow() + 60_000,
        beforePublish: async () => {
          if (during) return;
          during = await readMentionCoverage(engine, ['default']);
          // The deadline passes while the first batch publishes.
          Date.now = () => realNow() + 3_600_000;
        },
      });
    } finally {
      Date.now = realNow;
    }
    expect(during).toMatchObject({ state: 'pending', pending_pages: 451, degraded: true });
    expect(interrupted).toMatchObject({ state: 'pending', pages: 200, remaining: 251 });
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'pending', pending_pages: 251, degraded: true });
    expect((await call('entity', { name: 'QUCO' })).notices.join('\n')).toContain('[gbrain notice mention_index');
    expect((await mentionIndexUpgradeNotice(engine))?.join('\n')).toContain('251 page(s)');

    const resumed = await sweep(engine);
    expect(resumed.mentions).toMatchObject({ state: 'complete', pages: 251, remaining: 0 });
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'complete', pending_pages: 0 });
    expect(await mentionLinks(engine)).toEqual(linksBefore);
  }, 180_000);

  test('alias staleness counts only linkable entity pages', async () => {
    await account();
    await page(engine, 'companies/acme', 'company', 'Acme Example', 'A company.');
    for (let i = 0; i < 3; i++) await page(engine, `tickets/t${i}`, 'ticket', `Ticket ${i}`, 'Customer: QUCO');
    await page(engine, 'notes/n1', 'note', 'n1', 'Nothing relevant.');
    await sweep(engine);
    await asPreviousRelease({ aliasOnly: true });
    expect(await countMentionDuePages(engine)).toBe(0);
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'pending', pending_pages: 2 });
    expect((await mentionIndexUpgradeNotice(engine))?.join('\n')).toContain('2 page(s)');
    await sweep(engine);
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'complete', pending_pages: 0 });
  });
});

describe('upgrade from a brain built at the previous versions', () => {
  test('one cycle-budget sweep (no manual catch-up) derives the new grammar\'s multi-word alias and links it', async () => {
    await account();
    await page(engine, 'notes/n1', 'note', 'n1', 'Copper Fox renewal call next week.');
    await page(engine, 'tickets/t1', 'ticket', 'Ticket 1', 'Customer: QUCO');
    expect(deriveEntityAliases({ title: 'CRM record: Quormiro Capital', compiled_truth: ACCOUNT_BODY }).aliases.map(a => a.alias_norm))
      .toContain('copper fox');
    await sweep(engine);
    // What the previous grammar left: no multi-word declared alias, so no saved entry and no link from the note.
    await engine.executeRaw("DELETE FROM page_aliases WHERE alias_norm = 'copper fox'");
    await engine.executeRaw("DELETE FROM mention_gazetteer_entries WHERE name_norm = 'copper fox'");
    await engine.executeRaw(
      "DELETE FROM links l USING pages f WHERE f.id = l.from_page_id AND f.slug = 'notes/n1' AND l.link_source = 'mentions'");
    await asPreviousRelease();
    expect(await derivedAliases(engine, 'crm/123')).not.toContain('declared:copper fox');
    expect(await mentionLinks(engine)).toEqual(['tickets/t1 -> crm/123']);
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'pending', pending_pages: 3 });

    await sweep(engine, { timeBudgetMs: CYCLE_STALE_DRAIN_BUDGET_MS });
    expect(await derivedAliases(engine, 'crm/123')).toContain('declared:copper fox');
    expect(await mentionLinks(engine)).toEqual(['notes/n1 -> crm/123', 'tickets/t1 -> crm/123']);
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'complete', pending_pages: 0 });
    expect(await mentionIndexUpgradeNotice(engine)).toBeNull();
  });
});

describe('derivation settings on an indexed brain', () => {
  const indexed = async () => {
    await account();
    await page(engine, 'notes/n1', 'note', 'n1', 'Copper Fox renewal call next week.');
    await page(engine, 'tickets/t1', 'ticket', 'Ticket 1', 'Customer: QUCO');
    await sweep(engine);
    expect(await mentionLinks(engine)).toEqual(['notes/n1 -> crm/123', 'tickets/t1 -> crm/123']);
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'complete' });
  };

  test.each([
    ['mentions.multiword_aliases', 'false', false],
    ['mentions.alias_deny', 'Copper Fox', false],
    ['mentions.sibling_merge', 'false', true],
  ])('changing %s marks the pages due; the next pass applies it', async (key, value, keepsAlias) => {
    await indexed();
    await engine.setConfig(key, value);
    // A pass stopped before any batch: the fingerprint change alone marks every page due.
    expect(await runMentionPass(engine, { deadline: Date.now() - 1 })).toMatchObject({ state: 'pending', remaining: 3 });
    expect(await countMentionDuePages(engine)).toBe(3);
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'pending', pending_pages: 3, degraded: true });
    expect(await runMentionPass(engine)).toMatchObject({ state: 'complete', remaining: 0 });
    expect((await derivedAliases(engine, 'crm/123')).includes('declared:copper fox')).toBe(keepsAlias);
    expect(await mentionLinks(engine)).toEqual(keepsAlias ? ['notes/n1 -> crm/123', 'tickets/t1 -> crm/123'] : ['tickets/t1 -> crm/123']);
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'complete', pending_pages: 0 });
  });

  test('a denied alias comes back when mentions.alias_deny no longer names it', async () => {
    await indexed();
    await engine.setConfig('mentions.alias_deny', 'Copper Fox');
    await runMentionPass(engine);
    expect(await derivedAliases(engine, 'crm/123')).not.toContain('declared:copper fox');
    expect(await mentionLinks(engine)).toEqual(['tickets/t1 -> crm/123']);
    await engine.unsetConfig('mentions.alias_deny');
    expect(await runMentionPass(engine)).toMatchObject({ state: 'complete', remaining: 0 });
    expect(await derivedAliases(engine, 'crm/123')).toContain('declared:copper fox');
    expect(await mentionLinks(engine)).toEqual(['notes/n1 -> crm/123', 'tickets/t1 -> crm/123']);
    expect(await readMentionCoverage(engine, ['default'])).toMatchObject({ state: 'complete', pending_pages: 0 });
  });
});