Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.6 KB
Raw Blame
/**
 * GBRA-156: serial database round trips a warm serve request pays around its operation.
 *
 * 1. Protects: a warm request resolves its source and reads the config table in one round trip, on the warm CLI socket
 *    and on MCP stdio, with the same resolved source; the MCP hot-memory hook runs beside a read op's handler, and
 *    reads its two cache revalidation keys (withdrawal watermark, trust generation) together.
 * 2. Fails when: a source-resolution or config read waits on another one (the merged config before the resolution,
 *    tier 5's config key behind the tier-4 listing, the tier-5.5 emptiness probe behind the listing, the federated
 *    set's own sources read, stdio resolving outside the request's config snapshot), or the hook starts only after a
 *    read op settles, or it reads the watermark and the generation one after the other again.
 * 3. Existing coverage: test/cold-read-folded-statements.test.ts counts the sources reads of one snapshot, not their
 *    order; test/facts-context-injection.serial.test.ts pins the hook's payload, not when it runs.
 * 4. Seam: none. test/helpers/statement-depth.ts holds every PGLite statement and records its serial depth; the stdio
 *    arm runs the real `startMcpServer` (test/fixtures/mcp-stdio-round-trip-driver.ts), which tags each statement with
 *    the JSON-RPC request that sent it, so the server's background work (the resident persistence consumer ticks every
 *    250ms or more) never lands in, or deepens, the request's trace. A second stdio case forces that interleaving.
 */
import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { executeCliSocketRequest } from '../src/core/cli-socket/execute.ts';
import { cliSocketIdentity } from '../src/core/cli-socket/identity.ts';
import { withRequestConfigSnapshot } from '../src/core/config-snapshot.ts';
import { explicitReadBinding, localFederatedSourceIds, resolveSourceWithTier } from '../src/core/source-resolver.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { __resetHotMemoryCacheForTests, getBrainHotMemoryMeta } from '../src/core/facts/meta-hook.ts';
import { recordStatementDepth, type DepthRecord } from './helpers/statement-depth.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { withEnv } from './helpers/with-env.ts';

/** The reads a request makes to resolve its source and load its config. */
const RESOLUTION = /^SELECT (key, value|value) FROM config\b|\bFROM sources (ORDER BY id|WHERE)\b|^SELECT 1 AS one FROM pages WHERE source_id = 'default'/;
const WITHDRAWALS = /FROM fact_withdrawals WHERE source_id/;
const GENERATION = /FROM trust_policy_state WHERE id = 1/;
const SEARCH = /^WITH (top_pages|ranked) AS/;

/** Every read before the operation's first statement, and that first statement. */
function resolutionThenOp(records: DepthRecord[]): { resolution: DepthRecord[]; op: DepthRecord } {
  const first = records.findIndex(r => !RESOLUTION.test(r.sql));
  return { resolution: records.slice(0, first), op: records[first]! };
}

let engine: PGLiteEngine;
let depth: ReturnType<typeof recordStatementDepth>;
let root: string;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
  depth = recordStatementDepth(engine);
  root = mkdtempSync(join(tmpdir(), 'gbrain-serve-round-trips-'));
}, 60_000);

afterAll(async () => {
  await engine.disconnect();
  rmSync(root, { recursive: true, force: true });
});

beforeEach(async () => {
  await resetPgliteState(engine);
  __resetHotMemoryCacheForTests();
  const side = join(root, 'source-a-example');
  mkdirSync(side, { recursive: true });
  await engine.executeRaw(`INSERT INTO sources (id, name, local_path, config) VALUES ('source-a', 'source-a', $1, '{"federated": true}'::jsonb)`, [side]);
});

async function traced(fn: () => Promise<unknown>): Promise<DepthRecord[]> {
  depth.reset();
  await fn();
  return [...depth.records];
}

describe('warm CLI socket request', () => {
  const search = () => executeCliSocketRequest(engine, {
    v: 1, identity: cliSocketIdentity({ config: { engine: 'postgres' }, brainId: 'host', configDir: '/nonexistent', configFile: '/nonexistent/config.json', version: 'x', env: {} }),
    command: 'search', kind: 'op', op: 'search', params: { query: 'alpha' }, routing: { cwd: root, source_env: null }, cli: { quiet: true, timeout_ms: null },
  });

  test('resolves its source (tier 5.5) and reads its config in one round trip, then runs the op', async () => {
    await withEnv({ GBRAIN_SOURCE: undefined }, async () => {
      await search();
      let kind: unknown;
      const records = await traced(async () => { kind = (await search()).frame.kind; });
      const { resolution, op } = resolutionThenOp(records);
      expect(kind).toBe('result');
      expect(resolution.length).toBeGreaterThanOrEqual(2);
      expect(resolution.map(r => r.depth)).toEqual(resolution.map(() => 1));
      expect(op.depth).toBe(2);
    });
  });
});

describe('source resolution inside a request snapshot', () => {
  for (const defaultPages of [false, true]) {
    test(`tier 5.5 with ${defaultPages ? 'a non-empty' : 'an empty'} 'default': one round trip, the same answer as live reads`, async () => {
      if (defaultPages) await engine.putPage('notes/default-example', { type: 'note', title: 'Default example', compiled_truth: 'body' });
      const resolveScope = async () => {
        const resolved = await resolveSourceWithTier(engine, null, root);
        return { ...resolved, federated: await localFederatedSourceIds(engine, resolved.source_id, resolved.tier) };
      };
      await withEnv({ GBRAIN_SOURCE: undefined, GBRAIN_NO_SOLE_NON_DEFAULT_NUDGE: '1' }, async () => {
        const live = await resolveScope();
        let snapshot: unknown;
        const records = await traced(async () => { snapshot = await withRequestConfigSnapshot(engine, resolveScope); });
        expect(live.source_id).toBe(defaultPages ? 'default' : 'source-a');
        expect(snapshot).toEqual(live);
        expect(records.map(r => r.depth)).toEqual(records.map(() => 1));
      });
    });
  }

  test('an env-bound source is checked against the request\'s rows, not by its own read', async () => {
    const bind = async () => {
      const resolved = await resolveSourceWithTier(engine, null, root, { env: 'source-a' });
      return { ...resolved, binding: await explicitReadBinding(engine, resolved.source_id, resolved.tier) };
    };
    const live = await bind();
    let snapshot: unknown;
    const records = await traced(async () => { snapshot = await withRequestConfigSnapshot(engine, bind); });
    expect(snapshot).toEqual(live);
    expect(records.map(r => r.depth)).toEqual([1]);
    await expect(withRequestConfigSnapshot(engine, () => resolveSourceWithTier(engine, null, root, { env: 'source-missing' }))).rejects.toThrow(/not found or is archived/);
  });
});

describe('MCP hot-memory hook', () => {
  test('runs beside a read op and reads the withdrawal watermark and the trust generation together', async () => {
    const call = () => dispatchToolCall(engine, 'search', { query: 'alpha' }, { remote: true, sourceId: 'default', transport: 'stdio', metaHook: getBrainHotMemoryMeta });
    await call();
    __resetHotMemoryCacheForTests();
    const records = await traced(call);
    const withdrawals = records.find(r => WITHDRAWALS.test(r.sql))!;
    const generation = records.find(r => GENERATION.test(r.sql))!;
    const search = records.find(r => SEARCH.test(r.sql))!;
    expect(generation.depth).toBe(withdrawals.depth);
    expect(withdrawals.depth).toBeLessThanOrEqual(search.depth);
  });
});

describe('MCP stdio warm search (real startMcpServer)', () => {
  const REPO_ROOT = resolve(import.meta.dir, '..');
  const DRIVER = join(REPO_ROOT, 'test', 'fixtures', 'mcp-stdio-round-trip-driver.ts');
  const CHILD_STRIP = ['GBRAIN_DATABASE_URL', 'DATABASE_URL', 'GBRAIN_BRAIN_ID', 'GBRAIN_SOURCE', 'GBRAIN_SURFACE', 'GBRAIN_MCP_FORCE_SURFACE', 'GBRAIN_MCP_INSTRUCTIONS'];

  const warmSearch = async (extraEnv: Record<string, string>) => {
    const parent = mkdtempSync(join(tmpdir(), 'gbrain-stdio-round-trips-'));
    const log = join(parent, 'statements.ndjson');
    writeFileSync(log, '');
    mkdirSync(join(parent, '.gbrain'), { recursive: true });
    writeFileSync(join(parent, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', database_path: join(parent, 'db'), embedding_dimensions: 1536 }));
    const env = { ...process.env } as Record<string, string>;
    for (const k of CHILD_STRIP) delete env[k];
    Object.assign(env, { GBRAIN_HOME: parent, HOME: parent, GBRAIN_SWEEP: '0', GBRAIN_SKIP_STARTUP_HOOKS: '1', GBRAIN_SERVE_SYNC_IPC: '0', ROUND_TRIP_LOG: log, ...extraEnv });
    const proc = Bun.spawn([process.execPath, DRIVER], { cwd: parent, env, stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' });
    const responses = new Map<number, unknown>();
    const reader = (async () => {
      const decoder = new TextDecoder();
      let buf = '';
      for await (const chunk of proc.stdout) {
        buf += decoder.decode(chunk, { stream: true });
        let nl: number;
        while ((nl = buf.indexOf('\n')) >= 0) {
          const msg = JSON.parse(buf.slice(0, nl));
          buf = buf.slice(nl + 1);
          if (typeof msg.id === 'number') responses.set(msg.id, msg.result ?? msg.error);
        }
      }
    })();
    const send = (msg: unknown) => { proc.stdin.write(JSON.stringify(msg) + '\n'); proc.stdin.flush(); };
    const waitFor = async (id: number) => {
      const deadline = Date.now() + 60_000;
      while (!responses.has(id)) {
        if (proc.exitCode !== null) throw new Error(`driver exited ${proc.exitCode}: ${await new Response(proc.stderr).text()}`);
        if (Date.now() > deadline) throw new Error(`no response ${id}`);
        await Bun.sleep(10);
      }
      return responses.get(id);
    };
    const logged = () => readFileSync(log, 'utf8').split('\n').filter(Boolean).map(line => JSON.parse(line) as DepthRecord);
    const searchCall = (id: number) => send({ jsonrpc: '2.0', id, method: 'tools/call', params: { name: 'search', arguments: { query: 'alpha' } } });
    try {
      send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'round-trips', version: '0' } } });
      await waitFor(1);
      send({ jsonrpc: '2.0', method: 'notifications/initialized' });
      searchCall(2);
      await waitFor(2);
      searchCall(3);
      const result = await waitFor(3) as { isError?: boolean };
      const all = logged();
      const records = all.filter(r => r.scope === 3);
      expect(result.isError).toBeFalsy();
      const { resolution, op } = resolutionThenOp(records);
      expect(resolution.length).toBeGreaterThanOrEqual(2);
      expect(resolution.map(r => r.depth)).toEqual(resolution.map(() => 1));
      expect(op.depth).toBe(2);
      if (extraEnv.ROUND_TRIP_INTERLEAVE) {
        const background = all.findIndex(r => r.scope === null && r.sql === 'SELECT count(*)::int AS n FROM page_projection_jobs');
        expect(background).toBeGreaterThan(all.indexOf(resolution[0]!));
        expect(background).toBeLessThan(all.indexOf(op));
      }
      const withdrawals = records.find(r => WITHDRAWALS.test(r.sql));
      const generation = records.find(r => GENERATION.test(r.sql));
      const search = records.find(r => SEARCH.test(r.sql))!;
      expect(withdrawals?.depth).toBe(generation?.depth);
      expect(withdrawals!.depth).toBeLessThanOrEqual(search.depth);
    } finally {
      proc.kill('SIGKILL');
      await proc.exited;
      await reader.catch(() => {});
      rmSync(parent, { recursive: true, force: true });
    }
  };

  test('resolves its source and reads config in one round trip; the hook runs beside the op', () => warmSearch({}), 120_000);

  // Value: protects=the stdio trace counts only the request's own statements, so a background statement sent while the
  //   config snapshot read is in flight (a resident persistence consumer tick, by chance about 1 run in 6 on a loaded
  //   runner) neither becomes the "op" nor shifts its depth; fails_when=the trace goes back to "every statement logged
  //   after the previous call" (op.depth 1, expected 2, as full-ci saw); why_new=the case above meets the race only by
  //   chance; seam=ROUND_TRIP_INTERLEAVE in the driver sends the background statement; no_claim=how often ticks fire
  test('a background statement sent beside the request leaves its trace and depths unchanged', () => warmSearch({ ROUND_TRIP_INTERLEAVE: '3' }), 120_000);
});