Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.7 KB
Raw Blame
/**
 * #6007: a put_pages batch publishes on Postgres as grouped transactions
 * (group-publish.ts): one claim, one recovery-record transaction, one
 * publication transaction and one cleanup transaction for up to eight pages,
 * files included. Any member failure rolls the group back, restores every file
 * it published, and the members then publish one at a time so the failure is
 * attributed to its own page.
 */
import { describe, expect, test as bunTest } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, 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 { withEnv } from '../helpers/with-env.ts';
import type { PostgresEngine } from '../../src/core/postgres-engine.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, preparePersistedMutation } from '../../src/core/persistence/service.ts';
import { claimGroupFollowers, claimNextWrite, publicationGroupKey } from '../../src/core/persistence/journal.ts';
import { executeClaimedGroup } from '../../src/core/persistence/group-publish.ts';
import { OperationError } from '../../src/core/ops/contract.ts';
import type { WriteRequest } from '../../src/core/persistence/model.ts';
import { _resetWriteThroughCacheForTest } from '../../src/core/write-through.ts';

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

function test(name: string, run: () => Promise<void>) {
  bunTest(name, async () => {
    const fixtureDir = mkdtempSync(join(tmpdir(), 'gbrain-group-pg-'));
    const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
    engine = pg.engine;
    root = join(fixtureDir, 'brain'); mkdirSync(root);
    _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 {
      _resetWriteThroughCacheForTest();
      await pg.close();
      rmSync(fixtureDir, { recursive: true, force: true });
    }
  }, 60_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 JSON.parse((response.content[0] as { text: string }).text) as Record<string, any>;
}
const requests = () => engine.executeRaw<WriteRequest & { published: string | null }>(
  "SELECT *,published_at::text AS published FROM persistence_requests WHERE operation='put_page' ORDER BY sequence");
const recoveryBytes = async () => engine.executeRaw<{ key: string; n: number }>('SELECT key,recovery_bytes::int AS n FROM persistence_counters WHERE recovery_bytes<>0');

d('#6007 grouped put_pages publication on Postgres', () => {
  test('a batch publishes its file-bearing pages in one transaction with per-page receipts, files, effects and re-armed links', async () => {
    const slugs = ['notes/g-1', 'notes/g-2', 'notes/g-3', 'notes/g-4'];
    const result = await dispatch('put_pages', { request_id: randomUUID(), pages: slugs.map((slug, i) => page(slug, `Grouped body ${i} links [[${slugs[(i + 1) % 4]}]].`)), wait_ms: 20_000 });
    expect(result).toMatchObject({ state: 'committed', counts: { total: 4, committed: 4 } });
    const rows = await requests();
    expect(rows.map(row => row.state)).toEqual(['committed', 'committed', 'committed', 'committed']);
    expect(rows.every(row => publicationGroupKey(row) === publicationGroupKey(rows[0]!))).toBe(true);
    // now() is the transaction start: one shared publication timestamp proves one transaction.
    expect(new Set(rows.map(row => row.published)).size).toBe(1);
    expect(rows.every(row => row.recovery === null && row.publication_started)).toBe(true);
    expect(await recoveryBytes()).toEqual([]);
    for (const [i, slug] of slugs.entries()) {
      expect(readFileSync(join(root, `${slug}.md`), 'utf8')).toContain(`Grouped body ${i}`);
      expect((await engine.readPageSnapshot(slug, { sourceId: 'default' }))!.page.compiled_truth).toContain(`Grouped body ${i}`);
    }
    const effects = await engine.executeRaw<{ kind: string; n: number; reconciled: number }>(`SELECT kind,count(*)::int AS n,
      count(*) FILTER (WHERE data ? 'batch_reconciled')::int AS reconciled FROM persistence_effects GROUP BY kind ORDER BY kind`);
    expect(Object.fromEntries(effects.map(e => [e.kind, e.n]))).toMatchObject({ git: 4, embedding: 4, links: 4 });
    expect(effects.find(e => e.kind === 'links')!.reconciled).toBe(4);
    const attributed = await engine.executeRaw<{ slug: string; request: string }>(`SELECT slug,revision_write_request_id::text AS request FROM pages WHERE slug=ANY($1) ORDER BY slug`, [slugs]);
    expect(attributed.map(row => row.request)).toEqual(rows.map(row => row.id));
  });

  test('a member failure rolls the group back, restores its published files and publishes the members one at a time', async () => {
    const existing = join(root, 'notes', 'f-1.md');
    mkdirSync(join(root, 'notes'), { recursive: true });
    // The first page replaces an existing file so restoration has original bytes to bring back.
    expect((await dispatch('put_page', { ...page('notes/f-1', 'Original canonical body.'), request_id: randomUUID() })).state).toBe('committed');
    const original = readFileSync(existing, 'utf8');
    const [current] = await engine.executeRaw<{ revision: string }>("SELECT knowledge_revision::text AS revision FROM pages WHERE slug='notes/f-1'");
    await disposePersistenceConsumer(engine);
    // Hold the worktree so the admission's consumer cannot publish; the test drives the claim itself.
    const holder = await acquireWorktree((await getWorktreeBinding(engine, 'default'))!, 5000);
    expect(holder).not.toBeNull();
    let batch: Record<string, any>;
    try {
      batch = await dispatch('put_pages', { request_id: randomUUID(), wait_ms: 0, pages: [
        { ...page('notes/f-1', 'Replacement body.'), expected_revision: current!.revision },
        page('notes/f-2', 'Refused body.'), page('notes/f-3', 'Third body.')] });
      expect(batch.state).toBe('pending');
      await disposePersistenceConsumer(engine);
    } finally { await holder!.release(); }
    await engine.executeRaw("UPDATE persistence_requests SET state='queued',execution_token=NULL,claim_expires_at=NULL,blocked_reason=NULL WHERE state='running' AND recovery IS NULL");
    const head = (await claimNextWrite(engine, localHostId()))!;
    expect(head.slug).toBe('notes/f-1');
    const followers = await claimGroupFollowers(engine, head, publicationGroupKey(head)!, 7);
    expect(followers.map(row => row.slug)).toEqual(['notes/f-2', 'notes/f-3']);
    const settled: WriteRequest[] = [];
    let restoredBytes: string | undefined;
    let stagingLeft = true;
    const progressed = await executeClaimedGroup(engine, [head, ...followers], {
      hostId: localHostId(),
      prepare: async row => {
        const prepared = await preparePersistedMutation(engine, row, config as never);
        if (row.slug !== 'notes/f-2') return prepared;
        return { ...prepared, validate: async () => { throw new OperationError('revision_conflict', 'The page changed during preparation.', 'Fixture refusal.'); } };
      },
      settled: row => settled.push(row),
      hooks: { rolledBack: async () => {
        restoredBytes = readFileSync(existing, 'utf8');
        stagingLeft = (await engine.executeRaw('SELECT id FROM persistence_requests WHERE recovery IS NOT NULL')).length > 0;
      } },
    });
    expect(progressed).toBe(true);
    // The group had replaced f-1's file before f-2 failed; the rollback put the original bytes back first.
    expect(restoredBytes).toBe(original);
    expect(stagingLeft).toBe(false);
    expect(existsSync(join(root, 'notes', 'f-2.md'))).toBe(false);
    const rows = await requests();
    const bySlug = Object.fromEntries(rows.filter(row => row.intent?.page_batch).map(row => [row.slug, row]));
    expect(bySlug['notes/f-1']!.state).toBe('committed');
    expect(bySlug['notes/f-2']!.state).toBe('conflict');
    expect(bySlug['notes/f-2']!.error_code).toBe('revision_conflict');
    expect(bySlug['notes/f-3']!.state).toBe('committed');
    expect(new Set([bySlug['notes/f-1']!.published, bySlug['notes/f-3']!.published]).size).toBe(2);
    expect(settled.map(row => [row.slug, row.state])).toEqual([['notes/f-1', 'committed'], ['notes/f-2', 'conflict'], ['notes/f-3', 'committed']]);
    expect(readFileSync(existing, 'utf8')).toContain('Replacement body.');
    expect(readFileSync(join(root, 'notes', 'f-3.md'), 'utf8')).toContain('Third body.');
    expect(await engine.executeRaw("SELECT slug FROM pages WHERE slug='notes/f-2'")).toEqual([]);
    expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE recovery IS NOT NULL')).toEqual([]);
    expect(await recoveryBytes()).toEqual([]);
    const effects = await engine.executeRaw<{ slug: string; kind: string }>(`SELECT r.slug,e.kind FROM persistence_effects e JOIN persistence_requests r ON r.id=e.request_id
      WHERE r.intent ? 'page_batch' AND e.kind IN ('git','embedding') ORDER BY r.slug,e.kind`);
    expect(effects.map(e => `${e.slug}:${e.kind}`)).toEqual(['notes/f-1:embedding', 'notes/f-1:git', 'notes/f-3:embedding', 'notes/f-3:git']);
    const attributed = await engine.executeRaw<{ slug: string; request: string }>("SELECT slug,revision_write_request_id::text AS request FROM pages WHERE slug IN ('notes/f-1','notes/f-3') ORDER BY slug");
    expect(attributed.map(row => row.request)).toEqual([bySlug['notes/f-1']!.id, bySlug['notes/f-3']!.id]);
    // The receipt reads the per-page outcomes back.
    const status = await dispatch('put_pages', { request_id: batch!.batch_request_id });
    expect(status).toMatchObject({ state: 'partial', counts: { committed: 2, failed: 1 } });
  });

  test('claiming a group\'s followers locks only the members, never the write queued after them (#5984 G6)', async () => {
    await disposePersistenceConsumer(engine);
    const holder = await acquireWorktree((await getWorktreeBinding(engine, 'default'))!, 5000);
    expect(holder).not.toBeNull();
    try {
      expect((await dispatch('put_pages', { request_id: randomUUID(), wait_ms: 0, pages: [page('notes/l-1', 'One.'), page('notes/l-2', 'Two.'), page('notes/l-3', 'Three.')] })).state).toBe('pending');
      const single = await dispatch('put_page', { ...page('notes/l-after', 'Foreground after the batch.'), request_id: randomUUID(), wait_ms: 0 });
      expect(JSON.stringify(single)).toContain('pending');
      await disposePersistenceConsumer(engine);
    } finally { await holder!.release(); }
    await engine.executeRaw("UPDATE persistence_requests SET state='queued',execution_token=NULL,claim_expires_at=NULL,blocked_reason=NULL WHERE state='running' AND recovery IS NULL");
    const rows = await requests();
    const after = rows.find(row => row.slug === 'notes/l-after')!;
    const member = rows.find(row => row.slug === 'notes/l-3')!;
    const head = (await claimNextWrite(engine, localHostId()))!;
    expect(head.slug).toBe('notes/l-1');
    const update = Promise.withResolvers<void>(), release = Promise.withResolvers<void>();
    // Holds the claim transaction open between its locking read and its update, as a slow round trip would.
    const held = new Proxy(engine, { get(target, key) {
      if (key === 'transactionDirect') return <T>(fn: (tx: typeof engine) => Promise<T>) => target.transactionDirect(tx => fn(new Proxy(tx, { get(inner, name) {
        if (name === 'executeRaw') return async (sql: string, params?: unknown[]) => {
          if (sql.startsWith('UPDATE persistence_requests r SET state=')) { update.resolve(); await release.promise; }
          return inner.executeRaw(sql, params as never);
        };
        const value = Reflect.get(inner, name);
        return typeof value === 'function' ? value.bind(inner) : value;
      } }) as typeof engine));
      const value = Reflect.get(target, key);
      return typeof value === 'function' ? value.bind(target) : value;
    } }) as typeof engine;
    const claiming = claimGroupFollowers(held, head, publicationGroupKey(head)!, 7);
    await update.promise;
    const lockable = (id: string) => engine.transaction(tx => tx.executeRaw('SELECT id FROM persistence_requests WHERE id=$1::uuid FOR UPDATE NOWAIT', [id]))
      .then(() => true, (error: { code?: string }) => { if (error.code === '55P03') return false; throw error; });
    try {
      expect(await lockable(after.id)).toBe(true);
      expect(await lockable(member.id)).toBe(false);
    } finally { release.resolve(); }
    expect((await claiming).map(row => row.slug)).toEqual(['notes/l-2', 'notes/l-3']);
  });
});