Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.9 KB
Raw Blame
/**
 * #5983: on a managed brain whose tags / timeline_entries / takes carry a
 * nullable source_id column (not created by gbrain; every value NULL), the
 * managed writer guard read the NULL column instead of the parent page and
 * refused every coordinated INSERT/UPDATE as writer_coordinator_required.
 *
 * Contract: page children resolve their source through pages, so any
 * source_id column on them is ignored, NULL or not. Coordinated writes commit,
 * and everything the canonical schema refuses (no coordinator, another source,
 * a drifted value naming the allowed source) is still refused. Runs on PGLite
 * and, through test/e2e, Postgres.
 */
import { afterAll, beforeAll, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import type { OperationContext } from '../src/core/operations.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { MIGRATIONS, runMigrations } from '../src/core/migrate.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { configureGateway, resetGateway } from '../src/core/ai/gateway.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { withEnv } from './helpers/with-env.ts';
import { testBackends } from './helpers/test-backends.ts';
import { installPre5983Guard } from './helpers/pre-5983-guard.ts';

const backends = testBackends();
const engines: BrainEngine[] = [];
const dataDir = mkdtempSync(join(tmpdir(), 'gbrain-5983-db-'));
let closePostgres: (() => Promise<void>) | undefined;
const CHILDREN = ['tags', 'timeline_entries', 'takes'] as const;
const REFUSED = /writer_coordinator_required: canonical writer must use the persistence coordinator/;

beforeAll(async () => {
  configureGateway({ embedding_model: 'openai:text-embedding-3-large', embedding_dimensions: 1536, env: {} });
  if (backends.includes('pglite')) {
    const engine = new PGLiteEngine();
    await engine.connect({ database_path: dataDir }); await engine.initSchema(); engines.push(engine);
  }
  if (backends.includes('postgres')) {
    const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
    engines.push(pg.engine); closePostgres = pg.close;
  }
  for (const engine of engines) {
    for (const table of CHILDREN) await engine.executeRaw(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS source_id TEXT`);
  }
}, 120_000);
afterAll(async () => {
  for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
  await closePostgres?.(); resetGateway(); rmSync(dataDir, { recursive: true, force: true });
});

async function pageIn(engine: BrainEngine, sourceId: string): Promise<number> {
  await engine.executeRaw(`INSERT INTO sources(id,name) VALUES($1,$1) ON CONFLICT (id) DO NOTHING`, [sourceId]);
  const slug = `notes/p-${randomUUID().slice(0, 8)}`;
  const [row] = await engine.executeRaw<{ id: number }>(
    `INSERT INTO pages(source_id,slug,type,title,compiled_truth) VALUES($1,$2,'note','P','body') RETURNING id`, [sourceId, slug]);
  return row.id;
}

/** Runs `sql` with the guard on and `writeSources` as the coordinator's allowed set (undefined: no coordinator). */
async function guarded(engine: BrainEngine, writeSources: string[] | undefined, sql: string, params: unknown[]) {
  await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  try {
    await engine.transaction(async tx => {
      if (writeSources) await tx.executeRaw(`SELECT set_config('gbrain.write_sources',$1,true)`, [JSON.stringify(writeSources)]);
      await tx.executeRaw(sql, params);
    });
  } finally {
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  }
}

const INSERTS: Record<(typeof CHILDREN)[number], string> = {
  tags: `INSERT INTO tags(page_id,tag,tag_source) VALUES($1,'probe','added')`,
  timeline_entries: `INSERT INTO timeline_entries(page_id,date,source,summary) VALUES($1,'2026-10-01','test','probe')`,
  takes: `INSERT INTO takes(page_id,row_num,claim,kind,holder) VALUES($1,1,'probe','take','alice-example')`,
};
/** A drifted source_id naming the allowed source on a child of a page in another source. */
const CLAIMING_INSERTS: Record<(typeof CHILDREN)[number], string> = {
  tags: `INSERT INTO tags(page_id,tag,tag_source,source_id) VALUES($1,'probe','added','default')`,
  timeline_entries: `INSERT INTO timeline_entries(page_id,date,source,summary,source_id) VALUES($1,'2026-10-01','test','probe','default')`,
  takes: `INSERT INTO takes(page_id,row_num,claim,kind,holder,source_id) VALUES($1,1,'probe','take','alice-example','default')`,
};
const UPDATES: Record<(typeof CHILDREN)[number], string> = {
  tags: `UPDATE tags SET tag=tag||'x' WHERE page_id=$1`,
  timeline_entries: `UPDATE timeline_entries SET detail=COALESCE(detail,'')||'x' WHERE page_id=$1`,
  takes: `UPDATE takes SET claim=claim||'x' WHERE page_id=$1`,
};
const DELETES: Record<(typeof CHILDREN)[number], string> = {
  tags: `DELETE FROM tags WHERE page_id=$1`,
  timeline_entries: `DELETE FROM timeline_entries WHERE page_id=$1`,
  takes: `DELETE FROM takes WHERE page_id=$1`,
};
const count = async (engine: BrainEngine, table: string, pageId: number) =>
  Number((await engine.executeRaw<{ n: number }>(`SELECT count(*)::int AS n FROM ${table} WHERE page_id=$1`, [pageId]))[0].n);

test('coordinated INSERT, UPDATE and DELETE on NULL-source_id children of a page in the allowed source commit', async () => {
  for (const engine of engines) {
    for (const table of CHILDREN) {
      const pageId = await pageIn(engine, 'default');
      await guarded(engine, ['default'], INSERTS[table], [pageId]);
      expect(await count(engine, table, pageId)).toBe(1);
      await guarded(engine, ['default'], UPDATES[table], [pageId]);
      await guarded(engine, ['default'], DELETES[table], [pageId]);
      expect(await count(engine, table, pageId)).toBe(0);
    }
  }
});

test('the guard still refuses NULL-source_id child writes without the coordinator or for another source', async () => {
  for (const engine of engines) {
    for (const table of CHILDREN) {
      const pageId = await pageIn(engine, 'default');
      await expect(guarded(engine, undefined, INSERTS[table], [pageId])).rejects.toThrow(REFUSED);
      await expect(guarded(engine, ['other-source'], INSERTS[table], [pageId])).rejects.toThrow(REFUSED);
      await engine.executeRaw(INSERTS[table], [pageId]);
      await expect(guarded(engine, undefined, UPDATES[table], [pageId])).rejects.toThrow(REFUSED);
      await expect(guarded(engine, ['other-source'], UPDATES[table], [pageId])).rejects.toThrow(REFUSED);
      await expect(guarded(engine, undefined, DELETES[table], [pageId])).rejects.toThrow(REFUSED);
      await expect(guarded(engine, ['other-source'], DELETES[table], [pageId])).rejects.toThrow(REFUSED);
      expect(await count(engine, table, pageId)).toBe(1);
    }
  }
});

test('a populated drifted source_id is ignored: the parent page decides the source', async () => {
  for (const engine of engines) {
    for (const table of CHILDREN) {
      const pageId = await pageIn(engine, 'default');
      await engine.executeRaw(INSERTS[table], [pageId]);
      await engine.executeRaw(`UPDATE ${table} SET source_id='elsewhere' WHERE page_id=$1`, [pageId]);
      await guarded(engine, ['default'], UPDATES[table], [pageId]);
      await expect(guarded(engine, ['elsewhere'], UPDATES[table], [pageId])).rejects.toThrow(REFUSED);
      const foreignPage = await pageIn(engine, 'elsewhere');
      await expect(guarded(engine, ['default'], CLAIMING_INSERTS[table], [foreignPage])).rejects.toThrow(REFUSED);
      const moveTo = `UPDATE ${table} SET page_id=$2 WHERE page_id=$1`;
      await expect(guarded(engine, ['elsewhere'], moveTo, [pageId, foreignPage])).rejects.toThrow(REFUSED);
      await guarded(engine, ['default', 'elsewhere'], moveTo, [pageId, foreignPage]);
      expect(await count(engine, table, foreignPage)).toBe(1);
    }
  }
});

test('deleting a page still cascades its NULL-source_id children', async () => {
  for (const engine of engines) {
    const pageId = await pageIn(engine, 'default');
    for (const table of CHILDREN) await engine.executeRaw(INSERTS[table], [pageId]);
    await guarded(engine, ['default'], 'DELETE FROM pages WHERE id=$1', [pageId]);
    for (const table of CHILDREN) expect(await count(engine, table, pageId)).toBe(0);
  }
});

test('a managed put_page of a tagged page with timeline lines commits on a brain with the drifted columns', async () => {
  const logger = { info() {}, warn() {}, error() {} };
  for (const engine of engines) {
    const dir = mkdtempSync(join(tmpdir(), 'gbrain-5983-'));
    const root = join(dir, 'brain'); mkdirSync(root);
    const sourceId = `s5983-${randomUUID().slice(0, 8)}`;
    try {
      await withEnv({ GBRAIN_HOME: join(dir, 'home') }, async () => {
        await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [sourceId, root]);
        await engine.setConfig('sync.write_through', 'true');
        await claimWorktree(engine, sourceId, root);
        await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
        const ctx = { engine, sourceId, remote: false, config: { engine: engine.kind, embedding_disabled: true } as never, dryRun: false, logger } as OperationContext;
        const slug = 'people/alice-example';
        const content = '---\ntitle: Alice Example\ntype: person\ntags: [founder, example]\n---\nAlice builds things.\n\n---\n\n- **2026-09-30** | Met at demo day';
        await submitPageMutation(ctx, { operation: 'put_page', params: { slug, content, request_id: randomUUID() } });
        const [request] = await engine.executeRaw<{ state: string; error_message: string | null }>(
          `SELECT state,error_message FROM persistence_requests WHERE source_id=$1 AND slug=$2 ORDER BY sequence DESC LIMIT 1`, [sourceId, slug]);
        expect(request).toEqual({ state: 'committed', error_message: null });
        expect((await engine.getTags(slug, { sourceId })).sort()).toEqual(['example', 'founder']);
        expect((await engine.getTimeline(slug, { sourceId })).map(entry => entry.summary)).toEqual(['Met at demo day']);
      });
    } finally {
      await disposePersistenceConsumer(engine);
      await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
      rmSync(dir, { recursive: true, force: true });
    }
  }
}, 120_000);

test('upgrading a v196 brain with the pre-fix guard: v197 unblocks the refused write and is idempotent', async () => {
  const v197 = MIGRATIONS.find(migration => migration.version === 197)!;
  for (const engine of engines) {
    await installPre5983Guard(engine);
    const pageId = await pageIn(engine, 'default');
    await expect(guarded(engine, ['default'], INSERTS.tags, [pageId])).rejects.toThrow(REFUSED);
    const triggers = `SELECT tgrelid::regclass::text AS tbl, oid FROM pg_trigger WHERE tgname='managed_writer_guard' ORDER BY 1`;
    const before = await engine.executeRaw(triggers);
    for (let run = 0; run < 2; run++) {
      await engine.setConfig('version', '196');
      await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
      expect((await runMigrations(engine)).current).toBeGreaterThanOrEqual(197);
      await guarded(engine, ['default'], INSERTS.tags.replace("'probe'", `'probe-${run}'`), [pageId]);
      expect(await count(engine, 'tags', pageId)).toBe(run + 1);
      await expect(guarded(engine, undefined, INSERTS.tags.replace("'probe'", "'uncoordinated'"), [pageId])).rejects.toThrow(REFUSED);
    }
    expect(v197.sql).not.toMatch(/\b(TRIGGER|ALTER TABLE|LOCK)\b/);
    expect(await engine.executeRaw(triggers)).toEqual(before);
  }
}, 120_000);