Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.1 KB
Raw Blame
/**
 * #5914 (W14 P1.3): a canonical root recreated at the same path (new inode and
 * birth time) refused `recovery_required` from every verb, self-transfer
 * included. `--confirm-relocated-root` on `transfer prepare/accept
 * --self-transfer` waives only the inode/birth comparisons, and only when
 * token, brainId, worktreeId, root and coordination path all agree and the
 * outside-root reservation exists (a copied in-root stamp alone is never
 * authority). The waiver is persisted on the prepared record and required at
 * accept; the re-stamp goes through a compare-and-swap on the reservation.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { runPersistenceAdministration } from '../src/core/persistence/administration.ts';
import { acquireWorktree, getWorktreeBinding } from '../src/core/persistence/ownership.ts';
import { PHYSICAL_ROOT_MARKER, physicalRootReservationPath, readPhysicalRootReservation, readPhysicalRootStamp,
  replacePhysicalRootReservation } from '../src/core/persistence/physical-root-record.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { reviewedWriterIntent } from './helpers/writer-admin-intent.ts';
import { withEnv } from './helpers/with-env.ts';
import { testBackends } from './helpers/test-backends.ts';
import { recreateRoot } from './helpers/recreate-root.ts';

const backends = testBackends();
for (const kind of backends) describe(`relocated canonical root (${kind})`, () => {
  const directory = mkdtempSync(join(tmpdir(), 'gbrain-relocated-root-'));
  let engine: BrainEngine, close: (() => Promise<void>) | undefined;
  beforeAll(async () => {
    if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
    else { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); }
  }, 120_000);
  afterAll(async () => { await disposePersistenceConsumer(engine); if (close) await close(); else await engine.disconnect(); rmSync(directory, { recursive: true, force: true }); });

  async function fixture(run: (f: { root: string; home: string; source: string; binding: NonNullable<Awaited<ReturnType<typeof getWorktreeBinding>>> }) => Promise<void>) {
    const home = join(directory, randomUUID()), root = join(home, 'root'); mkdirSync(root, { recursive: true });
    const source = `relocated-${randomUUID().slice(0, 8)}`;
    writeFileSync(join(root, 'note.md'), 'Canonical example');
    await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [source, root]);
    await withEnv({ GBRAIN_HOME: home, GBRAIN_BRAIN_ID: 'host', GBRAIN_SOURCE: undefined }, async () => {
      await runPersistenceAdministration(engine, 'writer_claim', { source_id: source, path: root, ...await reviewedWriterIntent(engine, 'writer_claim') });
      await run({ root, home, source, binding: (await getWorktreeBinding(engine, source))! });
    });
  }
  const administer = async (operation: 'writer_transfer_prepare' | 'writer_transfer_accept', params: Record<string, unknown>) =>
    runPersistenceAdministration(engine, operation, { ...params, ...await reviewedWriterIntent(engine, operation) }) as Promise<any>;
  const storedSelfTransfer = async (worktreeId: string) => (await engine.executeRaw<{ manifest: { self_transfer?: { relocated?: boolean } } }>(
    'SELECT manifest FROM persistence_worktrees WHERE id=$1::uuid', [worktreeId]))[0].manifest?.self_transfer;

  for (const keepStamp of [true, false]) test(`recreated root (${keepStamp ? 'stamp restored from backup' : 'no stamp'}): refused without the waiver, repaired with it, waiver required at accept`, () => fixture(async f => {
    recreateRoot(f.root, { keepStamp });
    const live = statSync(f.root, { bigint: true });
    await expect(acquireWorktree(f.binding)).rejects.toMatchObject({ code: 'recovery_required' });
    await expect(administer('writer_transfer_prepare', { source_id: f.source, self_transfer: true })).rejects.toMatchObject({ code: 'recovery_required' });
    await expect(administer('writer_transfer_prepare', { source_id: f.source, confirm_relocated_root: true })).rejects.toMatchObject({ code: 'invalid_params' });

    const prepared = await administer('writer_transfer_prepare', { source_id: f.source, self_transfer: true, confirm_relocated_root: true });
    expect((await storedSelfTransfer(f.binding.worktree_id))?.relocated).toBe(true);
    const accept = { source_id: f.source, path: f.root, expected_epoch: prepared.owner_epoch, manifest: prepared.manifest.digest, self_transfer: true };
    await expect(administer('writer_transfer_accept', accept)).rejects.toMatchObject({ code: 'writer_transfer_conflict' });
    expect(readPhysicalRootReservation(f.root)!.initialInode).not.toBe(live.ino.toString());
    await administer('writer_transfer_accept', { ...accept, confirm_relocated_root: true });

    const binding = (await getWorktreeBinding(engine, f.source))!;
    expect(binding.owner_epoch).toBe('2'); expect(binding.state).toBe('active');
    const reservation = readPhysicalRootReservation(f.root)!, stamp = readPhysicalRootStamp(f.root)!;
    expect(reservation.initialInode).toBe(live.ino.toString()); expect(reservation.initialBirth).toBe(live.birthtimeNs.toString());
    expect(stamp.inode).toBe(live.ino.toString()); expect(stamp.token).toBe(reservation.token);
    const lock = await acquireWorktree(binding); expect(lock).not.toBeNull(); await lock?.release();
  }));

  test('the waiver is denied when the reservation is missing or any identity field disagrees; nothing is re-stamped', () => fixture(async f => {
    recreateRoot(f.root, { keepStamp: true });
    const reservationPath = physicalRootReservationPath(f.root), stampPath = join(f.root, PHYSICAL_ROOT_MARKER);
    const reservation = readFileSync(reservationPath, 'utf8'), stamp = readFileSync(stampPath, 'utf8');
    const waived = () => administer('writer_transfer_prepare', { source_id: f.source, self_transfer: true, confirm_relocated_root: true });
    const unchanged = () => { expect(readFileSync(stampPath, 'utf8')).toBe(stamp); expect(existsSync(reservationPath) ? readFileSync(reservationPath, 'utf8') : null).toBeOneOf([reservation, null]); };

    rmSync(reservationPath);
    await expect(waived()).rejects.toMatchObject({ code: 'recovery_required' });
    unchanged();
    writeFileSync(reservationPath, reservation, { mode: 0o600 });

    for (const [field, value] of [['token', randomUUID()], ['worktreeId', randomUUID()], ['brainId', randomUUID()], ['root', join(f.home, 'elsewhere')]] as const) {
      const damaged = { ...JSON.parse(stamp), [field]: value };
      writeFileSync(stampPath, JSON.stringify(damaged), { mode: 0o600 });
      await expect(waived()).rejects.toMatchObject({ code: 'recovery_required' });
      expect(readFileSync(reservationPath, 'utf8')).toBe(reservation);
      writeFileSync(stampPath, stamp, { mode: 0o600 });
    }
    writeFileSync(reservationPath, JSON.stringify({ ...JSON.parse(reservation), coordinationPath: join(f.home, 'other.lock') }), { mode: 0o600 });
    await expect(waived()).rejects.toMatchObject({ code: 'recovery_required' });
    writeFileSync(reservationPath, reservation, { mode: 0o600 });
    unchanged();
    expect(await storedSelfTransfer(f.binding.worktree_id)).toBeUndefined();
  }));

  test('the re-stamp is a compare-and-swap: a second identical swap is a no-op, a stale expectation refuses, and an accept after a foreign re-stamp refuses', () => fixture(async f => {
    recreateRoot(f.root, { keepStamp: true });
    const before = readPhysicalRootReservation(f.root)!;
    const live = statSync(f.root, { bigint: true });
    const next = { ...before, initialDevice: live.dev.toString(), initialInode: live.ino.toString(), initialBirth: live.birthtimeNs.toString() };
    replacePhysicalRootReservation(f.root, before, next);
    expect(readPhysicalRootReservation(f.root)).toEqual(next);
    replacePhysicalRootReservation(f.root, before, next);
    expect(readPhysicalRootReservation(f.root)).toEqual(next);
    expect(() => replacePhysicalRootReservation(f.root, before, { ...next, initialInode: '1' })).toThrow(expect.objectContaining({ code: 'recovery_required', detail: 'stale_record' }));
    expect(readPhysicalRootReservation(f.root)).toEqual(next);

    expect(() => replacePhysicalRootReservation(f.root, next, { ...next, token: randomUUID() })).toThrow(expect.objectContaining({ code: 'recovery_required' }));

    replacePhysicalRootReservation(f.root, next, before);
    const prepared = await administer('writer_transfer_prepare', { source_id: f.source, self_transfer: true, confirm_relocated_root: true });
    writeFileSync(physicalRootReservationPath(f.root), JSON.stringify({ ...before, initialInode: '1' }), { mode: 0o600 });
    await expect(administer('writer_transfer_accept', { source_id: f.source, path: f.root, expected_epoch: prepared.owner_epoch, manifest: prepared.manifest.digest,
      self_transfer: true, confirm_relocated_root: true })).rejects.toMatchObject({ code: 'recovery_required' });
  }));

  test('the waiver on an intact root is a plain self-transfer: the reservation is left as it is', () => fixture(async f => {
    const reservation = readFileSync(physicalRootReservationPath(f.root), 'utf8');
    const prepared = await administer('writer_transfer_prepare', { source_id: f.source, self_transfer: true, confirm_relocated_root: true });
    expect((await storedSelfTransfer(f.binding.worktree_id))?.relocated).toBe(true);
    await administer('writer_transfer_accept', { source_id: f.source, path: f.root, expected_epoch: prepared.owner_epoch, manifest: prepared.manifest.digest,
      self_transfer: true, confirm_relocated_root: true });
    expect(readFileSync(physicalRootReservationPath(f.root), 'utf8')).toBe(reservation);
    expect((await getWorktreeBinding(engine, f.source))!.owner_epoch).toBe('2');
  }));
});