Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.2 KB
Raw Blame
/**
 * GST-2552: a Git effect's commit whose branch moves under it never rebuilds its staged blobs over the commit that
 * moved it. The crash robot's `sync_and_connector_race_direct_write` interleaving, forced: a put_page's Git effect
 * stages its file and reads HEAD, then someone else writes the same file, stages it and commits it, then the effect's
 * `update-ref` finds HEAD moved. Before the fix the retry laid the old staged blob over the new HEAD, so HEAD silently
 * went back to the effect's bytes, the next sync imported nothing and the index kept the other writer's version staged.
 *
 * Protects: the other commit stays HEAD (Git is the parent), the effect completes `superseded` instead of committing
 * stale content, the next sync imports the other writer's edit, the checkout is clean, a later write of the page
 * commits, and the reference model finds no lost write.
 * Fails when: the effect's retry reuses a blob staged before the other commit, or reports the moved path committed.
 * The commitGitTargets cases pin each kind of move: a porcelain commit of the same file (superseded), a plumbing commit
 * that leaves the effect's bytes on disk (retried, then committed on the new HEAD), one that also changed the file
 * (superseded, index back to HEAD), a group with an untouched member (retried alone) and a removal the other commit
 * undid (superseded).
 * Seams: a `git` shim on PATH that makes the other commit just before the effect's first `update-ref`, and
 * `effectSeams.beforeUpdateRef` for the commitGitTargets cases; real repositories and real engines (PGLite, and
 * Postgres when DATABASE_URL is set).
 */
import { afterEach, describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { chmodSync, existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { ReferenceModel } from '../scripts/persistence/model.ts';
import { crossBoundarySequences } from '../scripts/persistence/generator.ts';
import { ROBOT_TOPOLOGY } from '../scripts/persistence/robot-driver.ts';
import { drain, runSteps } from '../scripts/persistence/crash-robot.ts';
import { contextFor, type OpObservation } from '../scripts/persistence/ops.ts';
import { operationsByName } from '../src/core/operations.ts';
import { OperationError } from '../src/core/ops/contract.ts';
import { gitChildEnv } from '../src/core/git-env.ts';
import { commitGitTargets, effectSeams } from '../src/core/persistence/effect-git.ts';
import { prepareTopology } from '../scripts/persistence/history-fixture.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { isolatedSharedSkillsEngine } from './helpers/shared-skills-engine.ts';
import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';

const realGit = Bun.spawnSync(['which', 'git']).stdout.toString().trim();

async function robotBrain<T>(url: string | undefined, path: string, run: (brain: Awaited<ReturnType<typeof prepareTopology>>) => Promise<T>): Promise<T> {
  const home = mkdtempSync(join(tmpdir(), 'gbrain-moved-head-'));
  try {
    return await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined, PATH: path }, async () => {
      const { engine, close } = await isolatedSharedSkillsEngine(url);
      try { return await run(await prepareTopology(engine, { sources: 2, worktrees: 2, root: join(home, 'checkouts'), prefix: 'robot', connector: true })); }
      finally { await disposePersistenceConsumer(engine); await close(); }
    });
  } finally { rmSync(home, { recursive: true, force: true }); }
}

for (const backend of testBackends()) for (const forced of [false, true]) {
  test(`${backend}: a commit of the same file ${forced ? 'between the effect\'s HEAD read and its update-ref' : 'after the effect'} wins and the next sync imports it`, async () => {
    const url = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;
    const schedule = crossBoundarySequences(ROBOT_TOPOLOGY).find(s => s.label === 'sync_and_connector_race_direct_write')!;
    const [put, sync] = ['sy0', 'sy1'].map(id => schedule.ops.find(d => d.id === id)!);
    const bin = mkdtempSync(join(tmpdir(), 'gbrain-moved-head-bin-'));
    const armed = join(bin, 'armed'), root = join(bin, 'root'), userContent = join(bin, 'user.md');
    writeFileSync(userContent, String(sync.args.content));
    writeFileSync(join(bin, 'git'), `#!/bin/bash
if [ -e "${armed}" ]; then
  for a in "$@"; do if [ "$a" = update-ref ]; then
    r="$(cat "${armed}")"; rm -f "${armed}"
    cp "${userContent}" "$r/notes/alpha.md"
    ${realGit} -C "$r" add -- notes/alpha.md >&2
    ${realGit} -C "$r" -c user.name=U -c [email protected] commit -q -m 'edit notes/alpha' -- notes/alpha.md >&2
    break
  fi; done
fi
exec ${realGit} "$@"
`);
    chmodSync(join(bin, 'git'), 0o755);
    try {
      await robotBrain(url, `${bin}:${process.env.PATH}`, async ({ world }) => {
        const dir = world.roots![sync.source]!;
        const g = (...a: string[]) => Bun.spawnSync([realGit, '-C', dir, ...a]).stdout.toString();
        if (forced) writeFileSync(armed, dir);
        const model = new ReferenceModel(world);
        world.descriptors = new Map(schedule.ops.map(d => [d.id, d]));
        await runSteps(world, model, { ...schedule, ops: [put], groups: [] });
        expect(await drain(world.engine, world)).toBe(true);
        expect(existsSync(armed)).toBe(false);
        if (!forced) {
          writeFileSync(join(dir, 'notes/alpha.md'), String(sync.args.content));
          g('add', '--', 'notes/alpha.md'); g('-c', 'user.name=U', '-c', '[email protected]', 'commit', '-q', '-m', 'edit notes/alpha', '--', 'notes/alpha.md');
        }
        expect(g('log', '-1', '--format=%s').trim()).toBe('edit notes/alpha');
        expect(g('show', 'HEAD:./notes/alpha.md')).toContain('mk-sy1');
        expect(g('status', '--porcelain', '--', 'notes/alpha.md')).toBe('');
        const [effect] = await world.engine.executeRaw<{ outcome: Record<string, unknown> | string }>(
          `SELECT e.outcome FROM persistence_effects e JOIN persistence_requests r ON r.id=e.request_id WHERE r.request_id=$1 AND e.kind='git'`, [put.requestId]);
        const outcome = typeof effect!.outcome === 'string' ? JSON.parse(effect!.outcome) : effect!.outcome;
        expect(outcome.git).toBe(forced ? 'superseded' : 'committed');

        const result = await operationsByName.sync_brain.handler(contextFor(world, 'local', sync.source), { source_id: sync.source, no_pull: true, no_embed: true }) as Record<string, unknown>;
        expect(result.modified).toBe(1);
        const [row] = await world.engine.executeRaw<{ t: string }>(`SELECT compiled_truth AS t FROM pages WHERE source_id=$1 AND slug='notes/alpha'`, [sync.source]);
        expect(row!.t).toContain('mk-sy1');
        const seen: OpObservation = { id: sync.id, kind: sync.kind, actor: sync.actor, source: sync.source, requestId: sync.requestId, status: 'committed', values: {}, raw: result };
        model.beginStep(true); await model.observe(sync, seen); await model.settleGroup([sync], [seen]);
        expect(model.violations).toEqual([]);

        const current = await world.engine.readPageSnapshot('notes/alpha', { sourceId: sync.source });
        await operationsByName.put_page.handler(contextFor(world, 'local', sync.source), { source_id: sync.source, slug: 'notes/alpha',
          content: String(put.args.content).replace('mk-sy0', 'mk-after'), expected_revision: current!.revision, request_id: crypto.randomUUID() });
        expect(await drain(world.engine, world)).toBe(true);
        expect(g('show', 'HEAD:./notes/alpha.md')).toContain('mk-after');
        expect(g('status', '--porcelain', '--', 'notes/alpha.md')).toBe('');
      });
    } finally { rmSync(bin, { recursive: true, force: true }); }
  }, 120_000);
}

const env = gitChildEnv();
const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env }).trim();
const roots: string[] = [];
function repo(files: Record<string, string>): string {
  const root = realpathSync(mkdtempSync(join(tmpdir(), 'gbrain-moved-head-repo-')));
  roots.push(root);
  git(root, 'init', '-q', '-b', 'main');
  git(root, 'config', 'user.name', 'Example Writer'); git(root, 'config', 'user.email', '[email protected]');
  for (const [path, body] of Object.entries(files)) put(root, path, body);
  git(root, 'add', '-A'); git(root, 'commit', '-qm', 'seed');
  return root;
}
function put(root: string, path: string, body: string): void {
  mkdirSync(join(root, path, '..'), { recursive: true });
  writeFileSync(join(root, path), body);
}
/** A commit of `path` holding `body` made without the checkout's index or files, as another tool's plumbing would. */
function plumbingCommit(root: string, path: string, body: string): void {
  const other = { ...env, GIT_INDEX_FILE: join(root, '.git', 'other-index') };
  const run = (args: string[], input?: string) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', env: other, input }).trim();
  run(['read-tree', 'HEAD']);
  run(['update-index', '--add', '--cacheinfo', `100644,${run(['hash-object', '-w', '--stdin'], body)},${path}`]);
  git(root, 'update-ref', 'refs/heads/main', run(['commit-tree', run(['write-tree']), '-p', 'HEAD', '-m', 'another commit']));
}
/** Runs `move` once, just before the next effect commit's first update-ref. */
function before(move: () => void): void {
  effectSeams.beforeUpdateRef = () => { effectSeams.beforeUpdateRef = undefined; move(); };
}
const committedByHand = (root: string, path: string, body: string) => {
  put(root, path, body);
  git(root, 'add', '--', path); git(root, 'commit', '-qm', 'another commit', '--', path);
};

afterEach(() => {
  effectSeams.beforeUpdateRef = undefined;
  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
});

describe('commitGitTargets when another commit lands before update-ref', () => {
  test('a porcelain commit of the same file wins: the target is superseded and the checkout is clean', async () => {
    const root = repo({ 'notes/a.md': 'a\n' });
    before(() => committedByHand(root, 'notes/a.md', 'a, by hand\n'));
    put(root, 'notes/a.md', 'a, by gbrain\n');
    const outcome = (await commitGitTargets(root, ['notes/a.md'])).get('notes/a.md');
    expect(outcome).toEqual({ git: 'superseded', reason: 'committed_by_another_writer' });
    expect(git(root, 'log', '-1', '--format=%s')).toBe('another commit');
    expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('a, by hand');
    expect(git(root, 'status', '--porcelain')).toBe('');
  });

  test('a plumbing commit that leaves the effect\'s bytes on disk is retried, and the retry commits on the new HEAD', async () => {
    const root = repo({ 'notes/a.md': 'a\n' });
    before(() => plumbingCommit(root, 'notes/a.md', 'a, elsewhere\n'));
    put(root, 'notes/a.md', 'a, by gbrain\n');
    const outcome = (await commitGitTargets(root, ['notes/a.md'])).get('notes/a.md');
    expect(outcome).toBeInstanceOf(OperationError);
    expect((outcome as OperationError).code).toBe('git_unavailable');
    expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('a, elsewhere');
    expect((await commitGitTargets(root, ['notes/a.md'])).get('notes/a.md')).toEqual({ git: 'committed' });
    expect(git(root, 'log', '-2', '--format=%s').split('\n')[1]).toBe('another commit');
    expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('a, by gbrain');
  });

  test('a plumbing commit that also changed the file supersedes it, and the index goes back to HEAD', async () => {
    const root = repo({ 'notes/a.md': 'a\n' });
    before(() => { plumbingCommit(root, 'notes/a.md', 'a, elsewhere\n'); put(root, 'notes/a.md', 'a, elsewhere\n'); });
    put(root, 'notes/a.md', 'a, by gbrain\n');
    expect((await commitGitTargets(root, ['notes/a.md'])).get('notes/a.md')).toMatchObject({ git: 'superseded' });
    expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('a, elsewhere');
    expect(git(root, 'status', '--porcelain')).toBe('');
  });

  test('in a group, only the moved file is superseded; the untouched one is put back and commits on retry', async () => {
    const root = repo({ 'notes/a.md': 'a\n', 'notes/b.md': 'b\n' });
    before(() => committedByHand(root, 'notes/a.md', 'a, by hand\n'));
    put(root, 'notes/a.md', 'a, by gbrain\n'); put(root, 'notes/b.md', 'b, by gbrain\n');
    const outcomes = await commitGitTargets(root, ['notes/a.md', 'notes/b.md']);
    expect(outcomes.get('notes/a.md')).toMatchObject({ git: 'superseded' });
    expect(outcomes.get('notes/b.md')).toBeInstanceOf(OperationError);
    expect(git(root, 'diff', '--cached', '--name-only')).toBe('');
    expect((await commitGitTargets(root, ['notes/b.md'])).get('notes/b.md')).toEqual({ git: 'committed' });
    expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('a, by hand');
    expect(git(root, 'show', 'HEAD:notes/b.md')).toBe('b, by gbrain');
    expect(git(root, 'status', '--porcelain')).toBe('');
  });

  test('a commit that swept in the effect\'s staged file is not a move: the retry finds it unchanged', async () => {
    const root = repo({ 'notes/a.md': 'a\n', 'notes/b.md': 'b\n' });
    before(() => { put(root, 'notes/b.md', 'b, by hand\n'); git(root, 'commit', '-qam', 'another commit'); });
    put(root, 'notes/a.md', 'a, by gbrain\n');
    expect((await commitGitTargets(root, ['notes/a.md'])).get('notes/a.md')).toBeInstanceOf(OperationError);
    expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('a, by gbrain');
    expect((await commitGitTargets(root, ['notes/a.md'])).get('notes/a.md')).toEqual({ git: 'unchanged' });
    expect(git(root, 'status', '--porcelain')).toBe('');
  });

  test('a removal whose file another commit put back is superseded; the file stays committed', async () => {
    const root = repo({ 'notes/a.md': 'a\n' });
    before(() => committedByHand(root, 'notes/a.md', 'a, put back by hand\n'));
    unlinkSync(join(root, 'notes/a.md'));
    expect((await commitGitTargets(root, ['notes/a.md'])).get('notes/a.md')).toMatchObject({ git: 'superseded' });
    expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('a, put back by hand');
    expect(git(root, 'status', '--porcelain')).toBe('');
  });
});