Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
18.8 KB
Raw Blame
/**
 * Real PostgreSQL take mutations through the operation and MCP boundaries.
 * Durable local principals, a claimed canonical root, and the native owner lock
 * exercise journal serialization, pending receipts, and same-ID replay. Files,
 * coherent snapshots, and structured take rows must agree after publication.
 */
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { hasDatabase } from './helpers.ts';
import { isolatedPersistencePostgres } from '../helpers/persistence-postgres.ts';
import { withEnv } from '../helpers/with-env.ts';
import type { PostgresEngine } from '../../src/core/postgres-engine.ts';
import { operations, OperationError, type OperationContext } from '../../src/core/operations.ts';
import { dispatchToolCall } from '../../src/mcp/dispatch.ts';
import { parseMarkdown, serializePageToMarkdown } from '../../src/core/markdown.ts';
import { parseTakesFence, TAKES_FENCE_BEGIN, TAKES_FENCE_END } from '../../src/core/takes-fence.ts';
import { registerLocalWriter, withVerifiedLocalRegistration, type LocalRegistration } from '../../src/core/persistence/identity.ts';
import { claimWorktree, getWorktreeBinding } from '../../src/core/persistence/ownership.ts';
import { acquireNativeLock } from '../../src/core/persistence/native-lock.ts';
import { disposePersistenceConsumer } from '../../src/core/persistence/service.ts';
import type { WriteReceipt } from '../../src/core/persistence/types.ts';

const RUN = hasDatabase();
const d = RUN ? describe : describe.skip;
const FILE_SOURCE = 'takes-owner-example';
const DB_SOURCE = 'takes-db-only-example';
const UNCLAIMED_SOURCE = 'takes-unclaimed-example';
const OWNER = 'people/owner-example';
const SLUG = {
  add: 'people/takes-add-example', concurrent: 'people/takes-concurrent-example',
  held: 'people/takes-lock-example', resolved: 'companies/takes-resolved-example',
  update: 'companies/takes-update-example', immutable: 'companies/takes-immutable-example',
  supersede: 'companies/takes-supersede-example', database: 'people/takes-database-example',
  unclaimed: 'people/takes-unclaimed-example',
};
const config = { engine: 'postgres' as const, embedding_disabled: true };
let engine: PostgresEngine;
let close: () => Promise<void>;
let home: string;
let repoDir: string;
let cli: LocalRegistration;
let stdio: LocalRegistration;
type MutationResult = WriteReceipt & Record<string, unknown> & { write_request: WriteReceipt };

function ctxOf(overrides: Partial<OperationContext> = {}): OperationContext {
  return {
    engine, config, logger: { info() {}, warn() {}, error() {} },
    dryRun: false, remote: false, sourceId: FILE_SOURCE, ...overrides,
  };
}

async function inBrain<T>(run: () => Promise<T>): Promise<T> {
  return withEnv({ GBRAIN_HOME: home }, async () => {
    try { return await run(); }
    finally { await disposePersistenceConsumer(engine); }
  });
}

function call(operation: string, params: Record<string, unknown>, ctx = ctxOf()) {
  const op = operations.find(o => o.name === operation)!;
  return withVerifiedLocalRegistration(engine, ctx.remote ? stdio : cli,
    () => op.handler(ctx, params));
}

/** A lost/pending acknowledgment retries only the original, caller-owned ID. */
async function committed(operation: string, params: Record<string, unknown> & { request_id: string }, ctx = ctxOf()): Promise<MutationResult> {
  expect(params.request_id).toBeString();
  const deadline = Date.now() + 25_000;
  while (true) {
    try {
      const result = await call(operation, params, ctx) as MutationResult;
      expect(result.state).toBe('committed');
      expect(result.write_request.request_id).toBe(params.request_id);
      return result;
    } catch (error) {
      if (!(error instanceof OperationError) || error.code !== 'write_pending' || Date.now() >= deadline) throw error;
      expect(error.writeRequest?.request_id).toBe(params.request_id);
    }
  }
}

async function expectOpError(pending: Promise<unknown>): Promise<OperationError> {
  try { await pending; }
  catch (error) { expect(error).toBeInstanceOf(OperationError); return error as OperationError; }
  throw new Error('Expected an OperationError.');
}

function pageFile(slug: string) { return join(repoDir, `${slug}.md`); }
async function snapshot(slug: string, sourceId = FILE_SOURCE) {
  const value = await engine.readPageSnapshot(slug, { sourceId });
  expect(value).not.toBeNull();
  return value!;
}
async function canonical(slug: string) {
  const state = await snapshot(slug);
  const bytes = readFileSync(pageFile(slug), 'utf8');
  // Compare all canonical fields without depending on PostgreSQL JSONB key order.
  expect(parseMarkdown(bytes, slug)).toEqual(parseMarkdown(serializePageToMarkdown(state.page, state.tags), slug));
  expect(parseTakesFence(bytes)).toEqual(parseTakesFence(state.page.compiled_truth));
  return { state, bytes };
}
async function rows(slug: string, sourceId = FILE_SOURCE) {
  const page_id = (await snapshot(slug, sourceId)).page.id;
  const [active, inactive] = await Promise.all([
    engine.listTakes({ page_id, sourceId, active: true }),
    engine.listTakes({ page_id, sourceId, active: false }),
  ]);
  return [...active, ...inactive].sort((a, b) => a.row_num - b.row_num);
}
async function journalRows(requestId: string, registration: LocalRegistration) {
  return engine.executeRaw(`SELECT request_id,state FROM persistence_requests
    WHERE principal_kind=$1 AND principal_id=$2 AND request_id=$3::uuid`,
  [registration.lane === 'cli' ? 'local_cli' : 'local_stdio', registration.id, requestId]);
}
async function mcp(operation: string, params: Record<string, unknown>, sourceId = FILE_SOURCE) {
  return withVerifiedLocalRegistration(engine, stdio, () => dispatchToolCall(engine, operation, params,
    { remote: true, transport: 'stdio', sourceId, config, takesHoldersAllowList: ['world'] }));
}

beforeAll(async () => {
  if (!RUN) return;
  home = mkdtempSync(join(tmpdir(), 'gbrain-takes-postgres-'));
  repoDir = join(home, 'canonical');
  mkdirSync(repoDir);
  await withEnv({ GBRAIN_HOME: home }, async () => {
    ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
    for (const [source, root] of [[FILE_SOURCE, repoDir], [DB_SOURCE, null],
      [UNCLAIMED_SOURCE, join(home, 'missing')]] as const) {
      await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [source, root]);
    }
    cli = await registerLocalWriter(engine, 'cli');
    stdio = await registerLocalWriter(engine, 'stdio', {
      sourceIds: [FILE_SOURCE, DB_SOURCE, UNCLAIMED_SOURCE],
      operations: ['takes_add', 'takes_update', 'takes_resolve', 'takes_supersede'],
      scopes: ['read', 'write'], slugPrefixes: null,
    });
    // Seed coherent canonical fixtures before claiming ownership. A database-only
    // fixture in an owned filesystem source would correctly refuse publication.
    for (const slug of Object.values(SLUG)) {
      const sourceId = slug === SLUG.database ? DB_SOURCE : slug === SLUG.unclaimed ? UNCLAIMED_SOURCE : FILE_SOURCE;
      const type = slug.startsWith('companies/') ? 'company' : 'person';
      const parsed = parseMarkdown(`---\ntitle: ${slug}\ntype: ${type}\n---\n\n## Takes\n`, slug);
      await engine.putPage(slug, parsed, { sourceId });
      if (sourceId === FILE_SOURCE) {
        const state = await snapshot(slug);
        mkdirSync(dirname(pageFile(slug)), { recursive: true });
        writeFileSync(pageFile(slug), serializePageToMarkdown(state.page, state.tags));
      }
    }
    await claimWorktree(engine, FILE_SOURCE, repoDir);
  });
}, 60_000);

afterAll(async () => {
  if (!RUN) return;
  try {
    await withEnv({ GBRAIN_HOME: home }, async () => {
      if (engine) await disposePersistenceConsumer(engine);
      if (close) await close();
    });
  } finally { if (home) rmSync(home, { recursive: true, force: true }); }
});

d('take persistence routing', () => {
  test('an intentional database-only source commits canonical content, rows, and a replayable receipt', () => inBrain(async () => {
    const params = { request_id: randomUUID(), slug: SLUG.database, claim: 'Durable without a repository', kind: 'take', holder: OWNER };
    const ctx = ctxOf({ sourceId: DB_SOURCE });
    const result = await committed('takes_add', params, ctx);
    const state = await snapshot(SLUG.database, DB_SOURCE);
    expect(result.persistence?.mode).toBe('database');
    expect(result.mirror_written).toBe(false);
    expect(result.revision).toBe(state.revision);
    expect(parseTakesFence(state.page.compiled_truth).takes[0].claim).toBe(params.claim);
    expect((await rows(SLUG.database, DB_SOURCE))[0]).toMatchObject({ row_num: 1, claim: params.claim, holder: OWNER, active: true });
    expect(existsSync(pageFile(SLUG.database))).toBe(false);
    const replay = await committed('takes_add', params, ctx);
    expect(replay.revision).toBe(state.revision);
    expect(replay.created_at).toBe(result.created_at);
    expect(await rows(SLUG.database, DB_SOURCE)).toHaveLength(1);
    expect(await journalRows(params.request_id, cli)).toHaveLength(1);
  }));

  test('an unclaimed configured root refuses before admission in the handler and MCP envelope', () => inBrain(async () => {
    const before = await snapshot(SLUG.unclaimed, UNCLAIMED_SOURCE);
    const params = { request_id: randomUUID(), slug: SLUG.unclaimed, claim: 'Must not land', kind: 'take', holder: 'world' };
    const error = await expectOpError(call('takes_add', params, ctxOf({ sourceId: UNCLAIMED_SOURCE })));
    expect(error.code).toBe('owner_unavailable');
    expect(error.writeRequest).toBeUndefined();
    const response = await mcp('takes_add', params, UNCLAIMED_SOURCE);
    expect(response.isError).toBe(true);
    const envelope = JSON.parse(response.content[0].text);
    expect(envelope.error).toBe('owner_unavailable');
    expect(envelope.write_request).toBeUndefined();
    expect(await snapshot(SLUG.unclaimed, UNCLAIMED_SOURCE)).toEqual(before);
    expect(await rows(SLUG.unclaimed, UNCLAIMED_SOURCE)).toHaveLength(0);
    expect(await journalRows(params.request_id, cli)).toHaveLength(0);
    expect(await journalRows(params.request_id, stdio)).toHaveLength(0);
    expect(existsSync(join(home, 'missing'))).toBe(false);
  }));
});

d('canonical take publication and native owner serialization', () => {
  test('add publishes the full fence and structured row together; replay preserves exact bytes and revision', () => inBrain(async () => {
    const params = { request_id: randomUUID(), slug: SLUG.add, claim: 'Ships weekly at demo day', kind: 'take',
      holder: OWNER, weight: 0.8, source: 'office-hours-notes', since: '2026-08' };
    const result = await committed('takes_add', params);
    expect(result).toMatchObject({ slug: SLUG.add, row_num: 1, holder: OWNER, mirror_written: true });
    expect(result.persistence).toMatchObject({ mode: 'filesystem', file_written: true });
    expect(result.mirror_warning).toBeUndefined();
    const before = await canonical(SLUG.add);
    expect(result.revision).toBe(before.state.revision);
    expect(before.bytes).toContain(TAKES_FENCE_BEGIN);
    expect(before.bytes).toContain(TAKES_FENCE_END);
    expect(before.bytes).toContain(`| 1 | Ships weekly at demo day | take | ${OWNER} | 0.8 | 2026-08 | office-hours-notes |`);
    const takes = await rows(SLUG.add);
    expect(takes).toHaveLength(1);
    expect(takes[0]).toMatchObject({ row_num: 1, claim: params.claim, kind: 'take', holder: OWNER, source: params.source, active: true });
    expect(takes[0].weight).toBeCloseTo(0.8, 5);
    const replay = await committed('takes_add', params);
    expect(replay.revision).toBe(result.revision);
    expect(await canonical(SLUG.add)).toEqual(before);
    expect(await rows(SLUG.add)).toEqual(takes);
  }));

  test('two concurrent requests serialize to distinct dense row numbers and replay without duplication', () => inBrain(async () => {
    const params = ['alpha', 'beta'].map(label => ({ request_id: randomUUID(), slug: SLUG.concurrent,
      claim: `Concurrent claim ${label}`, kind: 'take', holder: OWNER }));
    const results = await Promise.all(params.map(p => committed('takes_add', p)));
    expect(results.map(r => r.row_num).sort()).toEqual([1, 2]);
    for (const result of results) expect(result.mirror_written).toBe(true);
    const before = await canonical(SLUG.concurrent);
    const takes = await rows(SLUG.concurrent);
    expect(takes).toHaveLength(2);
    expect(new Set(takes.map(t => t.claim))).toEqual(new Set(params.map(p => p.claim)));
    expect(before.bytes.split(TAKES_FENCE_BEGIN).length - 1).toBe(1);
    await Promise.all(params.map(p => committed('takes_add', p)));
    expect(await canonical(SLUG.concurrent)).toEqual(before);
    expect(await rows(SLUG.concurrent)).toEqual(takes);
  }), 30_000);

  test('holding the actual owner lock returns the same pending receipt over both transports, then commits once', () => inBrain(async () => {
    const binding = (await getWorktreeBinding(engine, FILE_SOURCE))!;
    const held = await acquireNativeLock(binding.coordination_path!, { timeoutMs: 0 });
    expect(held).not.toBeNull();
    const before = await canonical(SLUG.held);
    const params = { request_id: randomUUID(), slug: SLUG.held, claim: 'Waits for the owner lock', kind: 'take', holder: 'world' };
    const ctx = ctxOf({ remote: true, transport: 'stdio', takesHoldersAllowList: ['world'] });
    let acceptedAt: string | undefined;
    try {
      const error = await expectOpError(call('takes_add', params, ctx));
      expect(error.code).toBe('write_pending');
      expect(error.writeRequest?.request_id).toBe(params.request_id);
      expect(['queued', 'running']).toContain(error.writeRequest!.state);
      acceptedAt = error.writeRequest?.created_at;
      expect(acceptedAt).toBeString();
      const response = await mcp('takes_add', params);
      expect(response.isError).toBe(true);
      const envelope = JSON.parse(response.content[0].text);
      expect(envelope.error).toBe('write_pending');
      expect(envelope.write_request.request_id).toBe(params.request_id);
      expect(envelope.write_request.created_at).toBe(acceptedAt);
      expect(await journalRows(params.request_id, stdio)).toHaveLength(1);
      expect(await canonical(SLUG.held)).toEqual(before);
      expect(await rows(SLUG.held)).toHaveLength(0);
    } finally { await held!.release(); }
    const result = await committed('takes_add', params, ctx);
    expect(result.created_at).toEqual(acceptedAt);
    expect(result.revision).not.toBe(before.state.revision);
    const after = await canonical(SLUG.held);
    expect(result.revision).toBe(after.state.revision);
    expect(await rows(SLUG.held)).toHaveLength(1);
    await committed('takes_add', params, ctx);
    expect(await canonical(SLUG.held)).toEqual(after);
    expect(await rows(SLUG.held)).toHaveLength(1);
  }), 30_000);
});

async function resolvedFixture(slug: string) {
  await committed('takes_add', { request_id: randomUUID(), slug, claim: 'Will close the round by Q4', kind: 'bet', holder: OWNER, weight: 0.6 });
  const params = { request_id: randomUUID(), slug, row_num: 1, quality: 'correct',
    evidence: 'Round closed', value: 25, unit: 'usd', resolved_by: OWNER };
  return { params, result: await committed('takes_resolve', params) };
}

d('resolved takes remain immutable', () => {
  test('resolve preserves the full resolution tuple and local resolver on canonical replay', () => inBrain(async () => {
    const { params, result } = await resolvedFixture(SLUG.resolved);
    expect(result).toMatchObject({ row_num: 1, quality: 'correct', resolved_by: OWNER });
    expect(result.mirror_warning).toBeUndefined();
    const before = await canonical(SLUG.resolved);
    expect(before.bytes).toContain('| correct |');
    expect(before.bytes).toContain('Round closed');
    const takes = await rows(SLUG.resolved);
    expect(takes).toHaveLength(1);
    expect(takes[0]).toMatchObject({ row_num: 1, resolved_quality: 'correct', resolved_outcome: true,
      resolved_by: OWNER, resolved_value: 25, resolved_unit: 'usd', resolved_source: 'Round closed' });
    expect(takes[0].resolved_at).not.toBeNull();
    await committed('takes_resolve', params);
    expect(await canonical(SLUG.resolved)).toEqual(before);
    expect(await rows(SLUG.resolved)).toEqual(takes);
  }));

  for (const [operation, slug, change] of [
    ['takes_update', SLUG.update, { weight: 0.9 }],
    ['takes_supersede', SLUG.immutable, { claim: 'Refused replacement' }],
  ] as const) {
    test(`${operation} returns a terminal invalid_params receipt and preserves the resolved row on replay`, () => inBrain(async () => {
      await resolvedFixture(slug);
      const before = await canonical(slug);
      const takes = await rows(slug);
      const params = { request_id: randomUUID(), slug, row_num: 1, ...change };
      for (let attempt = 0; attempt < 2; attempt++) {
        const error = await expectOpError(call(operation, params));
        expect(error.code).toBe('invalid_params');
        expect(error.message.toLowerCase()).toContain('resolved');
        expect(error.writeRequest).toMatchObject({ request_id: params.request_id, state: 'failed' });
      }
      expect(await canonical(slug)).toEqual(before);
      expect(await rows(slug)).toEqual(takes);
      expect(takes).toHaveLength(1);
      expect(takes[0].weight).toBeCloseTo(0.6, 5);
      expect(await journalRows(params.request_id, cli)).toHaveLength(1);
    }));
  }
});

d('supersede publication', () => {
  test('closes and links the old row, inherits metadata, and appends the replacement exactly once', () => inBrain(async () => {
    await committed('takes_add', { request_id: randomUUID(), slug: SLUG.supersede,
      claim: 'Will hit 10M ARR by Q4', kind: 'bet', holder: OWNER, weight: 0.6 });
    const params = { request_id: randomUUID(), slug: SLUG.supersede, row_num: 1, claim: 'Will hit 8M ARR by Q4 (revised)' };
    const result = await committed('takes_supersede', params);
    expect(result).toMatchObject({ old_row: 1, new_row: 2 });
    expect(result.mirror_warning).toBeUndefined();
    const takes = await rows(SLUG.supersede);
    expect(takes).toHaveLength(2);
    const old = takes.find(t => t.row_num === 1)!;
    const replacement = takes.find(t => t.row_num === 2)!;
    expect(old).toMatchObject({ active: false, superseded_by: 2, claim: 'Will hit 10M ARR by Q4' });
    expect(replacement).toMatchObject({ active: true, superseded_by: null, claim: params.claim, kind: 'bet', holder: OWNER });
    expect(replacement.weight).toBeCloseTo(0.5, 2);
    const before = await canonical(SLUG.supersede);
    expect(before.bytes).toContain('~~Will hit 10M ARR by Q4~~');
    expect(before.bytes).toContain('| 2 | Will hit 8M ARR by Q4 (revised) |');
    await committed('takes_supersede', params);
    expect(await canonical(SLUG.supersede)).toEqual(before);
    expect(await rows(SLUG.supersede)).toEqual(takes);
  }));
});