Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.9 KB
Raw Blame
/**
 * Guest notes (GBRA-504): every derived producer decides "guest source" with the read side's test (guestSourceSql): a
 * source is a guest source when its config says guest or guest_sources lists it, so losing one record never lets a
 * guest page feed derived rows. A lookup that fails, or a schema behind the guest-notes migration, counts as guest.
 *
 * Protects: (a) a source flagged guest in its config but missing from guest_sources gets no links, timeline rows,
 * facts or take proposals from the stale walk, the timeline walk, fact extraction, propose_takes or a scoped cycle,
 * while an owner page beside it still gets its link; (b) on a brain whose schema is behind the guest-notes migration
 * (the guest tables dropped) the skip holds or refuses, and never derives from the guest page. PGLite, repo-less.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { runCycle } from '../src/core/cycle.ts';
import { skipsGuestSource, withoutGuestSources } from '../src/core/guests/derived.ts';
import { GUEST_NOTES_MIGRATION } from '../src/core/guests/migration.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { extractStaleFromDB } from '../src/commands/extract.ts';
import { extractTimelineFromDB } from '../src/commands/extract-timeline-db.ts';
import { runExtractFacts } from '../src/core/cycle/extract-facts.ts';
import { runPhaseProposeTakes } from '../src/core/cycle/propose-takes.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { runPhaseExtractAtoms } from '../src/core/cycle/extract-atoms.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';

const FLAGGED = 'source-a';
const GUEST_PAGE = 'notes/flagged-a';
const page = (title: string, body: string) => '---\ntype: note\ntitle: ' + title + '\n---\n# ' + title + '\n\n' + body + '\n';

async function seed(engine: PGLiteEngine): Promise<void> {
  await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [FLAGGED]);
  await importFromContent(engine, 'people/erin-example', page('Erin', 'A person.'), { sourceId: FLAGGED, noEmbed: true } as never);
  await importFromContent(engine, GUEST_PAGE, page('Visitor', 'Met [[people/erin-example]] about the ledger.\n\n## Timeline\n\n- **2026-11-01** | Met Erin'),
    { sourceId: FLAGGED, noEmbed: true } as never);
  await importFromContent(engine, 'people/dan-example', '---\ntype: person\ntitle: Dan\n---\n# Dan\n', { noEmbed: true } as never);
  await importFromContent(engine, 'notes/owner-a', page('Owner', 'Met [[people/dan-example]].'), { noEmbed: true } as never);
}

const flag = (engine: PGLiteEngine) => engine.executeRaw("UPDATE sources SET config = config || '{\"guest\": true}'::jsonb WHERE id = $1", [FLAGGED]);

async function flaggedRows(engine: PGLiteEngine) {
  return (await engine.executeRaw<{ links: number; timeline: number; facts: number; proposals: number }>(
    'SELECT (SELECT count(*)::int FROM links l JOIN pages p ON p.id = l.from_page_id WHERE p.source_id = $1) AS links, '
      + '(SELECT count(*)::int FROM timeline_entries t JOIN pages p ON p.id = t.page_id WHERE p.source_id = $1) AS timeline, '
      + '(SELECT count(*)::int FROM facts f WHERE f.source_id = $1) AS facts, '
      + '(SELECT count(*)::int FROM take_proposals k WHERE k.source_id = $1) AS proposals', [FLAGGED]))[0]!;
}

const proposeCtx = (engine: PGLiteEngine) => ({ engine, config: {} as never, logger: { info() {}, warn() {}, error() {} } as never, dryRun: false, remote: false, sourceId: undefined });

/** Runs a producer; a refusal (thrown error) is an acceptable outcome, deriving from the guest page is not. */
async function holdsOrRefuses(run: () => Promise<unknown>): Promise<void> {
  try { await run(); } catch { /* refused: nothing derived */ }
}

describe('a source flagged guest in its config but missing from guest_sources (pglite, repo-less)', () => {
  let engine: PGLiteEngine;
  beforeAll(async () => {
    engine = new PGLiteEngine();
    await engine.connect({});
    await engine.initSchema();
    await seed(engine);
    expect(await engine.countStalePagesForExtraction({ sourceId: FLAGGED })).toBeGreaterThan(0);
    await flag(engine);
    expect((await engine.executeRaw('SELECT 1 FROM guest_sources WHERE source_id = $1', [FLAGGED])).length).toBe(0);
  }, 180_000);
  afterAll(async () => { await disposePersistenceConsumer(engine); await engine.disconnect(); }, 60_000);

  test('every skip helper treats it as a guest source', async () => {
    expect(await skipsGuestSource(engine, 'extract_facts', FLAGGED)).toBe(true);
    expect(await skipsGuestSource(engine, 'extract_atoms', FLAGGED)).toBe(true);
    expect(await withoutGuestSources(engine, 'chronicle', [FLAGGED, 'default'], id => id)).toEqual(['default']);
    expect(await engine.countStalePagesForExtraction({ sourceId: FLAGGED })).toBe(0);
  }, 60_000);

  test('the stale walk, the timeline walk and fact extraction derive nothing from it; the owner page still links', async () => {
    await extractStaleFromDB(engine, { dryRun: false, jsonMode: true, quiet: true, catchUp: false });
    await extractTimelineFromDB(engine, { dryRun: false, jsonMode: true, quiet: true });
    const facts = await runExtractFacts(engine, { sourceId: FLAGGED });
    expect({ scanned: facts.pagesScanned, failed: facts.pagesFailed }).toEqual({ scanned: 0, failed: 0 });
    expect(await flaggedRows(engine)).toEqual({ links: 0, timeline: 0, facts: 0, proposals: 0 });
    const [owner] = await engine.executeRaw<{ n: number }>("SELECT count(*)::int AS n FROM links l JOIN pages p ON p.id = l.from_page_id WHERE p.slug = 'notes/owner-a'");
    expect(owner!.n).toBeGreaterThan(0);
  }, 120_000);

  test('an unscoped propose_takes run never reads its pages', async () => {
    const scanned: string[] = [];
    await runPhaseProposeTakes(proposeCtx(engine) as never, { extractor: async ({ pagePath }) => { scanned.push(pagePath); return []; } });
    expect(scanned).toContain('notes/owner-a');
    expect(scanned.filter(slug => slug === GUEST_PAGE || slug === 'people/erin-example')).toEqual([]);
  }, 120_000);

  test('a cycle scoped to it skips the derived phases', async () => {
    const report = await runCycle(engine, { sourceId: FLAGGED, phases: ['extract_facts', 'propose_takes', 'orphans'], brainDir: null } as never);
    const byPhase = Object.fromEntries(report.phases.map(p => [p.phase, (p.details as { reason?: string } | undefined)?.reason]));
    expect({ extract_facts: byPhase.extract_facts, propose_takes: byPhase.propose_takes }).toEqual({ extract_facts: 'guest_source', propose_takes: 'guest_source' });
  }, 120_000);
});

describe('a brain whose schema is behind the guest-notes migration (v' + GUEST_NOTES_MIGRATION + ')', () => {
  let engine: PGLiteEngine;
  beforeAll(async () => {
    engine = new PGLiteEngine();
    await engine.connect({});
    await engine.initSchema();
    await seed(engine);
    await flag(engine);
    await engine.executeRaw('DROP TABLE guest_promotions, guest_marks, guest_sources CASCADE');
  }, 180_000);
  afterAll(async () => { await disposePersistenceConsumer(engine); await engine.disconnect(); }, 60_000);

  test('the skip helpers count the source as guest instead of failing', async () => {
    expect(await skipsGuestSource(engine, 'extract_facts', FLAGGED)).toBe(true);
    expect(await withoutGuestSources(engine, 'chronicle', [FLAGGED, 'default'], id => id)).not.toContain(FLAGGED);
  }, 60_000);

  test('every producer holds or refuses, and none derives from the guest page', async () => {
    const scanned: string[] = [];
    await holdsOrRefuses(() => extractStaleFromDB(engine, { dryRun: false, jsonMode: true, quiet: true, catchUp: false }));
    await holdsOrRefuses(() => extractTimelineFromDB(engine, { dryRun: false, jsonMode: true, quiet: true }));
    await holdsOrRefuses(() => runExtractFacts(engine, { sourceId: FLAGGED }));
    await holdsOrRefuses(() => runPhaseProposeTakes(proposeCtx(engine) as never, { extractor: async ({ pagePath }) => { scanned.push(pagePath); return []; } }));
    await holdsOrRefuses(() => runCycle(engine, { sourceId: FLAGGED, phases: ['extract_facts', 'propose_takes'], brainDir: null } as never));
    expect(scanned.filter(slug => slug === GUEST_PAGE || slug === 'people/erin-example')).toEqual([]);
    expect(await flaggedRows(engine)).toEqual({ links: 0, timeline: 0, facts: 0, proposals: 0 });
  }, 180_000);

  test('a skip caused by the failed guest lookup says the lookup failed', async () => {
    const atoms = await runPhaseExtractAtoms(engine, { sourceId: FLAGGED });
    expect(atoms.details).toMatchObject({ reason: 'guest_source_lookup_failed', source_id: FLAGGED });
    expect(String((atoms.details as { error?: string }).error)).toContain('guest_sources');
    const report = await runCycle(engine, { sourceId: FLAGGED, phases: ['extract_facts'], brainDir: null } as never);
    expect(report.phases.find(p => p.phase === 'extract_facts')?.details).toMatchObject({ reason: 'guest_source_lookup_failed', source_id: FLAGGED });
  }, 120_000);

  test('a page write is refused migrations_pending, not with the missing-table error', async () => {
    const [version] = await engine.executeRaw<{ value: string }>("SELECT value FROM config WHERE key = 'version'");
    await engine.executeRaw("UPDATE config SET value = $1 WHERE key = 'version'", [String(GUEST_NOTES_MIGRATION - 1)]);
    try {
      const out = await dispatchToolCall(engine, 'put_page', { slug: 'notes/behind-a', content: '---\ntype: note\ntitle: Behind\n---\n# Behind\n' }, { remote: false, sourceId: 'default' });
      const text = out.content.map(c => c.text).join('\n');
      expect({ isError: out.isError, migrationsPending: text.includes('migrations_pending'), raw: text.includes('does not exist') })
        .toEqual({ isError: true, migrationsPending: true, raw: false });
    } finally {
      await engine.executeRaw("UPDATE config SET value = $1 WHERE key = 'version'", [version!.value]);
    }
  }, 120_000);
});