Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.7 KB
Raw Blame
/**
 * #6188 foreground overhead budget (Codex Eng #15). A managed catch-up of
 * mostly clean files pays nothing for Tier 1: a file with no fence marker does
 * no fence work, a clean fence costs the one shared scan, and no clean file
 * issues any of the only statements Tier 1 can add (the `fences.normalize`
 * read, the stored-row loads for renumbering, the TE1 prior-takes read). The
 * catch-up alternates on identical sources with the fence step live and with
 * it replaced by a no-op; the statement totals and throughput of each arm are
 * printed for the release report (totals vary a little run to run with the
 * consumer's polling, so they are reported, not compared exactly).
 * FENCE_BENCH_FILES sizes it (default 300; the PR reports 10000) and
 * FENCE_BENCH_ROUNDS the live/no-op pairs (default 1). Synthetic content only.
 */
import { afterAll, beforeAll, expect, spyOn, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { performManagedSync } from '../src/core/persistence/sync-run.ts';
import * as tier1 from '../src/core/fence-repair/tier1.ts';
import * as fenceConfig from '../src/core/fence-repair/config.ts';
import * as importStep from '../src/core/fence-repair/import-step.ts';
import { withEnv } from './helpers/with-env.ts';

const FILES = Number(process.env.FENCE_BENCH_FILES ?? 300);
const ROUNDS = Number(process.env.FENCE_BENCH_ROUNDS ?? 1);
/** The statements Tier 1 can add: the switch read, the stored-row loads (renumber) and the TE1 prior-takes read. */
const TIER1_STATEMENT = (sql: string, params: unknown) => (Array.isArray(params) && params.includes('fences.normalize'))
  || sql === 'SELECT row_num, claim FROM takes WHERE page_id=$1' || sql === 'SELECT row_num FROM takes WHERE page_id=$1'
  || sql.startsWith('SELECT row_num, fact FROM facts WHERE source_id=$1 AND source_markdown_slug=$2 AND row_num IS NOT NULL');
const home = mkdtempSync(join(tmpdir(), 'gbrain-fence-overhead-'));
const env = { GBRAIN_HOME: home, GBRAIN_SYNC_FAILURES_DIR: home };
const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
const FH = '| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |\n|---|---|---|---|---|---|---|---|---|---|';
const TH = '| # | claim | kind | who | weight | since | source |\n|---|---|---|---|---|---|---|';

/** 90% plain notes, 10% pages with a clean facts and takes fence (the shape of a real catch-up). */
function fixture(i: number): [string, string] {
  if (i % 10 !== 0) return [`notes/n${String(i).padStart(5, '0')}.md`, `---\ntitle: Note ${i}\n---\nA synthetic observation number ${i} about routine work.\n`];
  return [`people/p${String(i).padStart(5, '0')}.md`, `---\ntitle: Person ${i}\n---\nA synthetic person page.\n\n<!--- gbrain:facts:begin -->\n${FH}\n`
    + `| 1 | Synthetic fact ${i} | fact | 1.0 | world | medium | 2026-01-01 |  | chat |  |\n<!--- gbrain:facts:end -->\n\n`
    + `<!--- gbrain:takes:begin -->\n${TH}\n| 1 | Synthetic take ${i} | take | brain | 0.7 | 2026-01 | chat |\n<!--- gbrain:takes:end -->\n`];
}

let engine: PGLiteEngine;
beforeAll(async () => withEnv(env, async () => { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); }), 120_000);
afterAll(async () => { await disposePersistenceConsumer(engine); await engine.disconnect(); rmSync(home, { recursive: true, force: true }); });

async function source(files: number): Promise<string> {
  const id = `bench-${randomUUID().replace(/-/g, '').slice(0, 16)}`, root = join(home, id);
  mkdirSync(root, { recursive: true }); git(root, 'init', '-q');
  for (let i = 0; i < files; i++) {
    const [path, content] = fixture(i);
    mkdirSync(join(root, path, '..'), { recursive: true });
    writeFileSync(join(root, path), content);
  }
  git(root, 'add', '-A'); git(root, '-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', 'fixture');
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  await engine.executeRaw("INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,'{}')", [id, root]);
  await claimWorktree(engine, id, root);
  await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  return id;
}

/** Every statement the engine sends to PGLite (its one connection carries transactions too), and the Tier 1 ones among them. */
function countStatements(): { count: () => number; tier1: () => number; restore: () => void } {
  const db = (engine as unknown as { _db: Record<'query' | 'exec', (...args: unknown[]) => Promise<unknown>> })._db;
  const original = { query: db.query, exec: db.exec };
  let n = 0, tier1Statements = 0;
  db.query = (...args) => { n++; if (TIER1_STATEMENT(String(args[0]), args[1])) tier1Statements++; return original.query.apply(db, args); };
  db.exec = (...args) => { n++; return original.exec.apply(db, args); };
  return { count: () => n, tier1: () => tier1Statements, restore: () => { db.query = original.query; db.exec = original.exec; } };
}

async function catchUp(live: boolean, files = FILES) {
  const id = await source(files);
  await disposePersistenceConsumer(engine);
  const stub = live ? null : spyOn(tier1, 'fenceStep').mockImplementation(() => ({ status: 'clean' }));
  const statements = countStatements();
  const started = performance.now();
  try {
    const result = await performManagedSync(engine, { sourceId: id, noPull: true, noEmbed: true, noExtract: true });
    const ms = performance.now() - started;
    await disposePersistenceConsumer(engine);
    expect(result.status).toBe('first_sync');
    expect(result.added).toBe(files);
    expect(result.fences_normalized).toBeUndefined();
    return { ms, statements: statements.count(), tier1: statements.tier1(), filesPerSecond: files / (ms / 1000) };
  } finally { statements.restore(); stub?.mockRestore(); }
}

test(`a ${FILES}-file managed catch-up of clean files: Tier 1 adds no statement, no switch read and no stored-row read`, () => withEnv(env, async () => {
  const switchReads = spyOn(fenceConfig, 'fencesNormalizeEnabled');
  const storedReads = spyOn(importStep, 'storedFenceRows');
  try {
    await catchUp(true, Math.min(FILES, 200)); // warm the JIT and the schema caches before measuring
    const runs = [];
    for (let round = 0; round < ROUNDS; round++) for (const live of [true, false]) runs.push({ live, ...await catchUp(live) });
    const live = runs.filter(r => r.live), stubbed = runs.filter(r => !r.live);
    const median = (xs: number[]) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)]!;
    const report = { files: FILES, rounds: ROUNDS, live_fps: live.map(r => Number(r.filesPerSecond.toFixed(1))), noop_fps: stubbed.map(r => Number(r.filesPerSecond.toFixed(1))),
      time_ratio_live_over_noop: Number((median(live.map(r => r.ms)) / median(stubbed.map(r => r.ms))).toFixed(3)),
      statements_live: live.map(r => r.statements), statements_noop: stubbed.map(r => r.statements) };
    console.log(`[fence-overhead] ${JSON.stringify(report)}`);
    // No clean file read the switch or the stored rows, and no Tier 1 statement was sent.
    expect(switchReads).not.toHaveBeenCalled();
    expect(storedReads).not.toHaveBeenCalled();
    expect(runs.map(r => r.tier1)).toEqual(runs.map(() => 0));
  } finally { switchReads.mockRestore(); storedReads.mockRestore(); }
}), 3_600_000);