Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.6 KB
Raw Blame
/**
 * #6712 PR 4b lane A: the proof-carrying confirm round (sync-pass-confirm.ts). A pass's round after the first reuses the
 * previous round's `I⋈P` and re-reads only the pages the pass wrote, when the database proves nothing else changed; any
 * change it cannot attribute to the pass takes the whole read. Each probe forces the change between round 1 and round 2
 * (the `sync:round_start` seam) and reads each round's verdict at `sync:level_read`.
 *
 * Protects:
 * - the clean case: round 2 reuses `I⋈P` and re-reads only the written pages (one changed file, one new file).
 * - a foreign page write over a pass import between rounds takes the whole read, and the page is not held (a stale reuse
 *   classifies the import again and holds it concurrent_write).
 * - another writer moving HEAD between rounds takes the whole read, and the pass imports the new commit.
 * - a foreign deletion of a hold between rounds takes the whole read.
 * - #6887 through the confirm round: a both-moved path held file_drift in round 1 stays held in a reused round 2, and a path
 *   that moves on both sides between rounds is held file_drift (a stale reuse holds it concurrent_write), the edit kept.
 *
 * PGLite here; Postgres through test/e2e/sync-pass-confirm-6712-postgres.test.ts.
 */
import { afterEach, describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { installFaultHook } from '../src/core/persistence/fault-points.ts';
import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
import { FILE_DRIFT_VERSION, readGitHold, SYNC_IMPORT_PROVENANCE_OP, writeGitHold } from '../src/core/persistence/sync-holds.ts';
import { performManagedSync } from '../src/core/persistence/sync-run.ts';
import { __resetTreeReuseForTests } from '../src/core/persistence/sync-tree-reuse.ts';
import { RECOVERY_VERSION } from '../src/core/markdown.ts';
import { managedBrain } from './helpers/managed-brain.ts';
import { testBackends } from './helpers/test-backends.ts';
import { waitFor } from './helpers/wait-for.ts';

const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
const commit = (root: string, message: string) => { git(root, 'add', '-A'); git(root, '-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', message); };
const note = (title: string, body: string) => `---\ntype: concept\ntitle: ${title}\n---\n\n${body}\n`;
const OPTS = { sourceId: 'default', noPull: true, noEmbed: true, noExtract: true };
const setup = ({ root }: { root: string }) => {
  mkdirSync(join(root, 'notes'), { recursive: true }); git(root, 'init', '-q');
  for (const slug of ['a', 'b', 'c']) writeFileSync(join(root, `notes/${slug}.md`), note(`notes/${slug}`, `The committed body of notes/${slug}.`));
  commit(root, 'notes');
};
const edit = (root: string, slug: string, body: string) => writeFileSync(join(root, `${slug}.md`), note(slug, body));
const incarnationOf = async (engine: BrainEngine) => (await engine.executeRaw<{ incarnation: string }>("SELECT incarnation::text FROM sources WHERE id='default'"))[0]!.incarnation;
const bodyOf = async (engine: BrainEngine, slug: string) => (await engine.getPage(slug, { sourceId: 'default' }))?.compiled_truth ?? '';
/** A database-only edit of `slug` (write-through off), committed before it returns. */
async function dbEdit(engine: BrainEngine, ctx: OperationContext, slug: string, body: string): Promise<void> {
  await engine.setConfig('sync.write_through', 'false');
  const requestId = randomUUID();
  await submitPageMutation(ctx, { operation: 'put_page', params: { slug, request_id: requestId,
    expected_revision: (await engine.readPageSnapshot(slug, { sourceId: 'default' }))!.revision, content: note(slug, body) } });
  await waitFor(async () => (await engine.executeRaw<{ state: string }>('SELECT state FROM persistence_requests WHERE request_id=$1::uuid', [requestId]))[0]?.state === 'committed',
    { timeoutMs: 30_000, label: `the database-only edit of ${slug} commits` });
  await engine.setConfig('sync.write_through', 'true');
}
type Verdict = { round: number; confirm: { taken: boolean; reason: string | null; rows: number; narrow?: string } | null };
/** One sync with `between` run before round 2 reads its level; the rounds' confirm verdicts and the result. */
async function pass(engine: BrainEngine, between: () => Promise<void> = async () => {}) {
  const verdicts: Verdict[] = [];
  let ran = false;
  installFaultHook(async (point, detail) => {
    if (point === 'sync:round_start' && detail.round === 2 && !ran) { ran = true; await between(); }
    if (point === 'sync:level_read') verdicts.push({ round: detail.round!, confirm: detail.level?.confirm ?? null });
  });
  try {
    // These are one pass's own rounds: round 1 reads whole, as in a new process (GBRA-133 cross-pass reuse is test/sync-level-reuse-across-gbra133.test.ts).
    __resetTreeReuseForTests();
    const result = await performManagedSync(engine, OPTS);
    return { status: result.status, held: (result.held ?? []).map(hold => [hold.path, hold.code]), verdicts };
  } finally { installFaultHook(undefined); }
}
const round2 = (run: { verdicts: Verdict[] }) => run.verdicts.find(verdict => verdict.round === 2)?.confirm;

afterEach(() => installFaultHook(undefined));

for (const backend of testBackends()) {
  const databaseUrl = backend === 'postgres' ? process.env.DATABASE_URL : undefined;
  const brain = (run: Parameters<typeof managedBrain>[0]) => managedBrain(run, { ...(databaseUrl ? { databaseUrl } : {}), setup });

  describe(`#6712 PR 4b confirm round (${backend})`, () => {
    test('clean case: round 2 reuses I⋈P and re-reads only the pages the pass wrote', () => brain(async ({ engine, root }) => {
      expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
      edit(root, 'notes/a', 'A committed change of notes/a.'); commit(root, 'change a');
      const changed = await pass(engine);
      expect({ status: changed.status, held: changed.held }).toEqual({ status: 'synced', held: [] });
      expect(changed.verdicts[0]).toEqual({ round: 1, confirm: null });
      expect(round2(changed)).toEqual({ taken: true, reason: null, rows: 1, narrow: 'taken' });
      expect(await bodyOf(engine, 'notes/a')).toContain('A committed change of notes/a.');
      edit(root, 'notes/d', 'A new file.'); commit(root, 'add d');
      const added = await pass(engine);
      expect({ status: added.status, confirm: round2(added) }).toEqual({ status: 'synced', confirm: { taken: true, reason: null, rows: 1, narrow: 'taken' } });
      expect(await bodyOf(engine, 'notes/d')).toContain('A new file.');
      expect((await performManagedSync(engine, OPTS)).pass).toBeUndefined();
    }), 180_000);

    test('a foreign page write over a pass import between rounds takes the whole read, and the page is not held', () => brain(async ({ engine, ctx, root }) => {
      expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
      edit(root, 'notes/a', 'A committed change of notes/a.'); edit(root, 'notes/b', 'A committed change of notes/b.'); commit(root, 'change a and b');
      const run = await pass(engine, () => dbEdit(engine, ctx, 'notes/b', 'DBONLYMARKER written after the import.'));
      // The database moved after the file was imported (the file is unchanged since): nothing to import, nothing to hold.
      expect({ status: run.status, held: run.held }).toEqual({ status: 'synced', held: [] });
      expect(round2(run)).toEqual({ taken: false, reason: 'foreign_page_write', rows: 0 });
      expect(await bodyOf(engine, 'notes/b')).toContain('DBONLYMARKER written after the import.');
      expect(await readGitHold(engine, 'default', await incarnationOf(engine), 'notes/b.md')).toBeNull();
    }), 180_000);

    test('another writer moving HEAD between rounds takes the whole read, and the pass imports the new commit', () => brain(async ({ engine, root }) => {
      expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
      edit(root, 'notes/a', 'A committed change of notes/a.'); commit(root, 'change a');
      const run = await pass(engine, async () => { edit(root, 'notes/b', 'A commit landing mid-pass.'); commit(root, 'change b mid-pass'); });
      expect(round2(run)).toEqual({ taken: false, reason: 'key', rows: 0 });
      expect({ status: run.status, held: run.held }).toEqual({ status: 'synced', held: [] });
      expect(await bodyOf(engine, 'notes/b')).toContain('A commit landing mid-pass.');
      expect((await performManagedSync(engine, OPTS)).pass).toBeUndefined();
    }), 180_000);

    test('a foreign deletion of a hold between rounds takes the whole read', () => brain(async ({ engine, root }) => {
      expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
      const incarnation = await incarnationOf(engine);
      const page = (await engine.readPageSnapshot('notes/c', { sourceId: 'default' }))!;
      await engine.transaction(tx => writeGitHold(tx, { source_id: 'default', incarnation, path: 'notes/c.md', source_path: 'notes/c.md', slug: 'notes/c', page_id: Number(page.page.id),
        code: 'file_drift', message: 'Synthetic file_drift hold.', upstream_version: null, observed_at: new Date().toISOString(), run_id: null, mode: 'managed',
        // Screened by the current drift rule, so the pass leaves it alone (an older one is re-screened and released by the pass itself, GST-2568).
        meta: { recovery_version: RECOVERY_VERSION, drift_version: FILE_DRIFT_VERSION, blob_oid: git(root, 'rev-parse', 'HEAD:notes/c.md'), page_revision: page.revision } } as never));
      edit(root, 'notes/a', 'A committed change of notes/a.'); commit(root, 'change a');
      const run = await pass(engine, async () => { await engine.executeRaw("DELETE FROM op_checkpoints WHERE op='sync-hold' AND fingerprint=$1", [`default:${incarnation}:notes/c.md`]); });
      expect(round2(run)).toEqual({ taken: false, reason: 'holds', rows: 0 });
      expect(run.status).toBe('synced');
      expect(await readGitHold(engine, 'default', incarnation, 'notes/c.md')).toBeNull();
    }), 180_000);

    test('#6887 through the confirm round: a both-moved path held in round 1 stays held file_drift in the reused round 2', () => brain(async ({ engine, ctx, root }) => {
      expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
      await dbEdit(engine, ctx, 'notes/b', 'DBONLYMARKER the agent edit.');
      const [page] = await engine.executeRaw<{ id: number }>("SELECT id FROM pages WHERE source_id='default' AND slug='notes/b'");
      await engine.executeRaw('DELETE FROM op_checkpoints WHERE op=$1 AND fingerprint=$2', [SYNC_IMPORT_PROVENANCE_OP, `default:${await incarnationOf(engine)}:${page!.id}`]);
      edit(root, 'notes/a', 'A committed change of notes/a.'); edit(root, 'notes/b', 'The second committed body.'); commit(root, 'change a and b');
      const run = await pass(engine);
      expect(round2(run)).toEqual({ taken: true, reason: null, rows: 1, narrow: 'taken' });
      expect({ status: run.status, held: run.held }).toEqual({ status: 'synced', held: [['notes/b.md', 'file_drift']] });
      expect(await bodyOf(engine, 'notes/b')).toContain('DBONLYMARKER the agent edit.');
      expect(readFileSync(join(root, 'notes/b.md'), 'utf8')).toContain('The second committed body.');
      expect((await readGitHold(engine, 'default', await incarnationOf(engine), 'notes/b.md'))?.code).toBe('file_drift');
    }), 180_000);

    test('#6887 through the confirm round: a path that moves on both sides between rounds is held file_drift, the edit kept', () => brain(async ({ engine, ctx, root }) => {
      expect((await performManagedSync(engine, OPTS)).status).toBe('first_sync');
      edit(root, 'notes/a', 'A committed change of notes/a.'); commit(root, 'change a');
      const run = await pass(engine, async () => {
        await dbEdit(engine, ctx, 'notes/b', 'DBONLYMARKER a mid-pass edit.');
        edit(root, 'notes/b', 'A committed change of notes/b mid-pass.'); commit(root, 'change b mid-pass');
      });
      expect({ status: run.status, held: run.held }).toEqual({ status: 'synced', held: [['notes/b.md', 'file_drift']] });
      expect(round2(run)?.taken).toBe(false);
      expect(await bodyOf(engine, 'notes/b')).toContain('DBONLYMARKER a mid-pass edit.');
      expect((await readGitHold(engine, 'default', await incarnationOf(engine), 'notes/b.md'))?.code).toBe('file_drift');
    }), 180_000);
  });
}