Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.1 KB
Raw Blame
import { describe, expect, test as bunTest } from 'bun:test';
import { mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from 'node:fs';
import { randomUUID } from 'node:crypto';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { hasDatabase } from './helpers.ts';
import { isolatedPersistencePostgres } from '../helpers/persistence-postgres.ts';
import { LEGACY_EMBEDDING_CONFIG } from '../helpers/legacy-embedding-config.ts';
import { withEnv } from '../helpers/with-env.ts';
import type { PostgresEngine } from '../../src/core/postgres-engine.ts';
import { configureGateway, resetGateway, __setEmbedTransportForTests } from '../../src/core/ai/gateway.ts';
import { dispatchToolCall } from '../../src/mcp/dispatch.ts';
import { acquireWorktree, claimWorktree, getWorktreeBinding } from '../../src/core/persistence/ownership.ts';
import { localHostId, registerLocalWriter, withVerifiedLocalRegistration, type LocalRegistration } from '../../src/core/persistence/identity.ts';
import { disposePersistenceConsumer } from '../../src/core/persistence/service.ts';
import { runPersistenceEffects } from '../../src/core/persistence/effects.ts';
import { installFaultHook } from '../../src/core/persistence/fault-points.ts';
import { _resetWriteThroughCacheForTest } from '../../src/core/write-through.ts';

const d = hasDatabase() ? describe : describe.skip;
let engine: PostgresEngine;
let root: string;
let registration: LocalRegistration;
const config = { engine: 'postgres' as const, embedding_disabled: true };
const slug = 'notes/persistence-example';
const content = (body: string) => `---\ntitle: Example\ntype: note\n---\n\n${body}`;

// Each case owns a new database. Permanent receipt IDs and ownership records are
// never truncated, and the explicitly supplied test URL is only the admin route.
function test(name: string, run: () => Promise<void>) {
  bunTest(name, async () => {
    const fixtureDir = mkdtempSync(join(tmpdir(), 'gbrain-put-pg-'));
    // Pin the fresh schema before initialization; embedding cases seed 1536-d vectors.
    configureGateway({ ...LEGACY_EMBEDDING_CONFIG, env: {} });
    const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
    engine = pg.engine;
    config.embedding_disabled = true;
    root = join(fixtureDir, 'brain'); mkdirSync(root);
    resetGateway(); _resetWriteThroughCacheForTest();
    try {
      await withEnv({ GBRAIN_HOME: join(fixtureDir, 'home') }, async () => {
        await engine.setConfig('sync.repo_path', root);
        await claimWorktree(engine, 'default', root);
        registration = await registerLocalWriter(engine, 'stdio', {
          sourceIds: ['default'], operations: null, scopes: ['read', 'write'], slugPrefixes: ['notes'],
        });
        try { await run(); } finally { await disposePersistenceConsumer(engine); }
      });
    } finally {
      __setEmbedTransportForTests(null); resetGateway(); _resetWriteThroughCacheForTest();
      await pg.close();
      rmSync(fixtureDir, { recursive: true, force: true });
    }
  }, 30_000);
}

async function dispatch(name: string, params: Record<string, unknown>) {
  const response = await withVerifiedLocalRegistration(engine, registration, () => dispatchToolCall(engine, name, params, {
    remote: true, config, sourceId: 'default',
    auth: { token: 'fixture', clientId: 'fixture-client', scopes: ['read', 'write'], sourceId: 'default', boundSlugPrefixes: ['notes'] },
    logger: { info() {}, warn() {}, error() {} },
  }));
  return { response, payload: JSON.parse((response.content[0] as { text: string }).text), params };
}
async function put(body: string, pageSlug = slug) {
  const current = await engine.readPageSnapshot(pageSlug, { sourceId: 'default', includeDeleted: true });
  return dispatch('put_page', { slug: pageSlug, content: content(body), request_id: randomUUID(),
    ...(current ? { expected_revision: current.revision } : {}) });
}
async function snapshot() {
  return engine.transaction(async tx => ({
    snapshot: await tx.readPageSnapshot(slug, { sourceId: 'default', includeDeleted: true }),
    chunks: await tx.getChunks(slug, { sourceId: 'default' }),
    versions: await tx.executeRaw('SELECT * FROM page_versions ORDER BY id'),
  }));
}
async function embedding(result: Awaited<ReturnType<typeof put>>, expectedReason: string) {
  const deadline = Date.now() + 10_000;
  let receipt: Awaited<ReturnType<typeof dispatch>> | undefined;
  while (Date.now() < deadline) {
    receipt = await dispatch('get_write_request', { request_id: result.params.request_id });
    expect(receipt.response.isError).not.toBe(true);
    if (receipt.payload.effects?.some((effect: { kind: string; reason?: string }) =>
      effect.kind === 'embedding' && effect.reason === expectedReason)) return receipt;
    await Bun.sleep(25);
  }
  throw new Error(`Embedding effect did not settle: ${JSON.stringify(receipt?.payload.effects)}`);
}

d('Postgres put_page persistence', () => {
  test('native lock contention preserves the prior revision and returns a durable same-ID receipt', async () => {
    const first = await put('Original canonical revision.');
    expect(first.payload.state).toBe('committed');
    await disposePersistenceConsumer(engine);
    const before = await snapshot();
    const disk = readFileSync(join(root, `${slug}.md`), 'utf8');
    const binding = await getWorktreeBinding(engine, 'default');
    expect(binding).not.toBeNull();
    const holder = await acquireWorktree(binding!, 5000);
    expect(holder).not.toBeNull();
    let accepted: Awaited<ReturnType<typeof put>>;
    try {
      accepted = await put('Queued replacement revision.');
      expect(await snapshot()).toEqual(before);
      expect(readFileSync(join(root, `${slug}.md`), 'utf8')).toBe(disk);
      expect(accepted.response.isError).toBe(true);
      expect(accepted.payload.error).toBe('write_pending');
      expect(accepted.payload.write_request.request_id).toBe(accepted.params.request_id);
      expect(['queued', 'running']).toContain(accepted.payload.write_request.state);
    } finally {
      await holder!.release();
    }
    const committed = await dispatch('put_page', accepted!.params);
    expect(committed.response.isError).not.toBe(true);
    expect(committed.payload.state).toBe('committed');
    expect(committed.payload.request_id).toBe(accepted!.params.request_id);
    expect(committed.payload.revision).not.toBe(first.payload.revision);
    expect((await dispatch('put_page', accepted!.params)).payload.revision).toBe(committed.payload.revision);
    expect((await snapshot()).versions).toHaveLength(1);
    expect(readFileSync(join(root, `${slug}.md`), 'utf8')).toContain('Queued replacement revision.');
  });

  test('file rename failure rolls back page, tags, chunks, and version in the real transaction', async () => {
    expect((await put('Before failed rename.')).payload.state).toBe('committed');
    const before = await snapshot();
    const file = join(root, `${slug}.md`);
    const bytes = readFileSync(file, 'utf8');
    renameSync(file, `${file}.original`);
    mkdirSync(file);
    const failed = await put('Rejected replacement.');
    expect(failed.response.isError).toBe(true);
    expect(failed.payload.error).toBe('storage_error');
    expect(failed.payload.write_request.state).toBe('failed');
    expect(JSON.stringify(failed.response)).not.toContain(root);
    expect(await snapshot()).toEqual(before);
    expect(readFileSync(`${file}.original`, 'utf8')).toBe(bytes);
  });

  test('pgvector failure is reported after the canonical write without rolling back its receipt', async () => {
    config.embedding_disabled = false;
    configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536, env: { OPENAI_API_KEY: 'sk-test' } });
    await engine.executeRaw('ALTER TABLE content_chunks ALTER COLUMN embedding TYPE vector(2)');
    __setEmbedTransportForTests(async ({ values }) => {
      expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page.compiled_truth).toBe('Persists before vector validation.');
      expect(readFileSync(join(root, `${slug}.md`), 'utf8')).toContain('Persists before vector validation.');
      return { values, warnings: [], embeddings: values.map(() => Array(1536).fill(0.1)), usage: { tokens: 1 } };
    });
    const result = await put('Persists before vector validation.');
    expect(result.response.isError).not.toBe(true);
    expect(result.payload.status).toBe('created_or_updated');
    expect(result.payload.write_through.written).toBe(true);
    const observed = await embedding(result, 'effect_unavailable');
    expect(observed.payload.state).toBe('committed');
    expect(observed.payload.revision).toBe(result.payload.revision);
    expect(observed.payload.effects).toContainEqual({ kind: 'embedding', state: 'queued', reason: 'effect_unavailable' });
    expect((await engine.getChunks(slug, { sourceId: 'default' })).every(chunk => chunk.embedding_is_null)).toBe(true);
    expect((await dispatch('put_page', result.params)).payload.revision).toBe(result.payload.revision);
  });

  test('provider dimension mismatch fails its effect once without changing the committed canonical receipt', async () => {
    config.embedding_disabled = false;
    configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536, env: { OPENAI_API_KEY: 'sk-test' } });
    let calls = 0;
    __setEmbedTransportForTests(async ({ values }) => {
      calls++;
      return { values, warnings: [], embeddings: values.map(() => [0.1, 0.2]), usage: { tokens: 1 } };
    });
    const result = await put('Canonical content survives an invalid provider dimension.');
    expect(result.response.isError).not.toBe(true);
    expect(result.payload.write_through.written).toBe(true);
    const observed = await embedding(result, 'embedding_configuration');
    expect(observed.payload.state).toBe('committed');
    expect(observed.payload.revision).toBe(result.payload.revision);
    expect(observed.payload.effects).toContainEqual({ kind: 'embedding', state: 'failed', reason: 'embedding_configuration' });
    expect((await engine.getChunks(slug, { sourceId: 'default' })).every(chunk => chunk.embedding_is_null)).toBe(true);
    await disposePersistenceConsumer(engine);
    await runPersistenceEffects(engine, config, { hostId: localHostId(), limit: 20 });
    expect(calls).toBe(1);
    expect(readFileSync(join(root, `${slug}.md`), 'utf8')).toContain('Canonical content survives an invalid provider dimension.');
    expect((await dispatch('put_page', result.params)).payload.revision).toBe(result.payload.revision);
    expect(calls).toBe(1);
  });

  test('slow embedding releases the worktree before other writes and rejects superseded vectors', async () => {
    config.embedding_disabled = false;
    const started = Promise.withResolvers<void>();
    const release = Promise.withResolvers<void>();
    configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536, env: { OPENAI_API_KEY: 'sk-test' } });
    __setEmbedTransportForTests(async ({ values }) => {
      if (values.some(value => value.includes('Older pending revision.'))) {
        started.resolve();
        await release.promise;
      }
      return { values, warnings: [], embeddings: values.map(() => new Array(1536).fill(0.1)), usage: { tokens: 1 } };
    });
    const pending = put('Older pending revision.');
    await started.promise;
    try {
      expect(readFileSync(join(root, `${slug}.md`), 'utf8')).toContain('Older pending revision.');
      expect((await put('Independent saved page.', 'notes/independent')).payload.state).toBe('committed');
      expect((await put('Replacement saved revision.')).payload.state).toBe('committed');
    } finally {
      release.resolve();
      await pending;
    }
    const original = await pending;
    const observed = await embedding(original, 'revision_changed');
    expect(observed.payload.state).toBe('committed');
    expect(observed.payload.revision).toBe(original.payload.revision);
    expect(observed.payload.effects).toContainEqual({ kind: 'embedding', state: 'committed', reason: 'revision_changed' });
    expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))?.page.compiled_truth).toBe('Replacement saved revision.');
    expect(readFileSync(join(root, `${slug}.md`), 'utf8')).toContain('Replacement saved revision.');
    expect((await engine.getChunks(slug, { sourceId: 'default' })).map(chunk => chunk.chunk_text)).toEqual(['Replacement saved revision.']);
    expect((await dispatch('put_page', original.params)).payload.revision).toBe(original.payload.revision);
  });
  test('an embedding effect whose page moves on between its page read and its projection read is superseded on that attempt', async () => {
    config.embedding_disabled = false;
    configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: 1536, env: { OPENAI_API_KEY: 'sk-test' } });
    __setEmbedTransportForTests(async ({ values }) => ({ values, warnings: [], embeddings: values.map(() => new Array(1536).fill(0.1)), usage: { tokens: 1 } }));
    // The first embedding effect has read its page at the older revision; the newer one commits (sealed) before it reads the projection.
    const moved = Promise.withResolvers<Awaited<ReturnType<typeof put>>>();
    let held = false;
    installFaultHook(async point => {
      if (point !== 'effect:embedding:page_read' || held) return;
      held = true;
      moved.resolve(await put('Newer saved revision.'));
    });
    try {
      const older = await put('Older saved revision.');
      expect(older.payload.state).toBe('committed');
      expect((await moved.promise).payload.state).toBe('committed');
      const observed = await embedding(older, 'revision_changed');
      expect(observed.payload.effects).toContainEqual({ kind: 'embedding', state: 'committed', reason: 'revision_changed' });
      // One attempt: never requeued as projection_pending for a revision no projection will be sealed at.
      expect(await engine.executeRaw(`SELECT e.attempts, e.error_code FROM persistence_effects e JOIN persistence_requests r ON r.id=e.request_id
        WHERE r.request_id=$1::uuid AND e.kind='embedding'`, [older.params.request_id])).toEqual([{ attempts: 1, error_code: null }]);
    } finally { installFaultHook(undefined); }
  });
});