Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.6 KB
Raw Blame
/**
 * Shared fixture for the dream reverse-write probes (GBRA-131 D-7 synthesize, D-8 patterns, #6982): a brain whose
 * source checkout is a temp directory, one dream output page imported twice (the second import is the child's write,
 * which keeps the first in page_versions), and the reverse-write under test run against it.
 */
import { describe, expect, spyOn, test } from 'bun:test';
import * as fs from 'node:fs';
import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import type { BrainEngine } from '../../src/core/engine.ts';
import { importFromContent } from '../../src/core/import-file.ts';
import { serializePageToMarkdown } from '../../src/core/markdown.ts';
import { managedPersistenceEnabled } from '../../src/core/persistence/ownership.ts';
import { _resetWriteThroughCacheForTest } from '../../src/core/write-through.ts';
import { isolatedSharedSkillsEngine } from '../helpers/shared-skills-engine.ts';
import { withEnv } from '../helpers/with-env.ts';
import { expectUnitNotAborted } from './harness.ts';

export type ReverseWrite = (engine: BrainEngine, brainDir: string, refs: Array<{ slug: string; source_id: string }>,
  nativeSourceId?: string, signal?: AbortSignal, held?: string[]) => Promise<number>;

const SOURCE = 'default';
export const DREAM_SLUG = 'wiki/originals/ideas/alice-example-idea';
const V1 = 'FIRST-RUN-MARKER: Alice Example prefers small launches.';
const V2 = 'CHILD-WRITE-MARKER: Alice Example now ships weekly at acme-example.';
const FILE_EDIT = 'FILE-ONLY-EDIT-MARKER: a paragraph saved in the editor, not yet synced.';
const LATE_EDIT = 'CONCURRENT-EDIT-MARKER: written while the reverse-write ran.';
const page = (body: string) => `---\ntype: note\ntitle: Alice Example idea\n---\n# Alice Example idea\n\n${body}\n`;

interface Brain {
  engine: BrainEngine;
  root: string;
  file(path?: string): string;
  path: string;
  body(): Promise<string>;
  /** The first run's file: the page as it was before the child's write. */
  writeFirstRunFile(extra?: string): string;
  run(engine?: BrainEngine): Promise<{ written: number; held: string[] }>;
}

async function withBrain(databaseUrl: string | undefined, reverseWrite: ReverseWrite, run: (b: Brain) => Promise<void>): Promise<void> {
  const home = mkdtempSync(join(tmpdir(), 'gbrain-dream-rw-'));
  try {
    await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
      _resetWriteThroughCacheForTest();
      const { engine, close } = await isolatedSharedSkillsEngine(databaseUrl);
      try {
        expect(await managedPersistenceEnabled(engine)).toBe(false);
        const root = join(home, 'brain');
        mkdirSync(root, { recursive: true });
        await engine.executeRaw("UPDATE sources SET local_path = $1 WHERE id = 'default'", [root]);
        await importFromContent(engine, DREAM_SLUG, page(V1), { noEmbed: true, sourceId: SOURCE });
        const first = (await engine.readPageSnapshot(DREAM_SLUG, { sourceId: SOURCE }))!;
        const firstRunFile = serializePageToMarkdown(first.page, first.tags);
        await importFromContent(engine, DREAM_SLUG, page(`${V1}\n\n${V2}`), { noEmbed: true, sourceId: SOURCE });
        const path = join(root, `${DREAM_SLUG}.md`);
        const b: Brain = {
          engine, root, path,
          file: (p = path) => readFileSync(p, 'utf8'),
          body: async () => (await engine.executeRaw<{ compiled_truth: string }>(
            'SELECT compiled_truth FROM pages WHERE source_id = $1 AND slug = $2', [SOURCE, DREAM_SLUG]))[0]!.compiled_truth,
          writeFirstRunFile(extra) {
            const bytes = extra ? firstRunFile.replace(V1, `${V1}\n\n${extra}`) : firstRunFile;
            mkdirSync(dirname(path), { recursive: true });
            writeFileSync(path, bytes);
            return bytes;
          },
          async run(on = engine) {
            const held: string[] = [];
            const written = await reverseWrite(on, root, [{ slug: DREAM_SLUG, source_id: SOURCE }], SOURCE, undefined, held);
            return { written, held };
          },
        };
        await run(b);
      } finally { await close(); }
    });
  } finally { rmSync(home, { recursive: true, force: true }); }
}

/** The engine that runs `after` once the reverse-write has read the page history it compares the file with. */
function editsAfterComparison(engine: BrainEngine, after: () => void): BrainEngine {
  let fired = false;
  return new Proxy(engine, {
    get(target, prop) {
      if (prop === 'executeRaw') return async (sql: string, ...rest: unknown[]) => {
        const rows = await (target.executeRaw as (...a: unknown[]) => Promise<unknown>).call(target, sql, ...rest);
        if (!fired && /UNION ALL[\s\S]*page_versions/.test(sql)) { fired = true; after(); }
        return rows;
      };
      const value = Reflect.get(target, prop, target);
      return typeof value === 'function' ? value.bind(target) : value;
    },
  });
}

const heldFor = (held: string[]) => held.filter(h => h.startsWith(`${DREAM_SLUG} (file_database_drift`));

/** The reverse-write cases every dream phase's writer must pass, on one engine arm (from `pathologicalArms()`). */
export function reverseWriteCases(id: string, phase: string, reverseWrite: ReverseWrite, { backend, databaseUrl }: { backend: string; databaseUrl: string | undefined }): void {
  describe(`${id} ${phase} reverse-write and a file that differs from the database (${backend})`, () => {
    test(`${id} file-newer: an unimported file edit is kept, the page is held with file_database_drift and the database is untouched`, async () => {
      await withBrain(databaseUrl, reverseWrite, async b => {
        const edited = b.writeFirstRunFile(FILE_EDIT);
        const bodyBefore = await b.body();
        const result = await expectUnitNotAborted(() => b.run());
        const held = heldFor(result.held);
        expect({ written: result.written, held: held.length, fix: held.some(h => h.includes('gbrain sync --source default')) })
          .toEqual({ written: 0, held: 1, fix: true });
        expect({ file: b.file() === edited, body: (await b.body()) === bodyBefore }).toEqual({ file: true, body: true });
      });
    }, 180_000);

    test(`${id} db-newer: a file the child's write replaced (kept in page_versions) is rewritten with the new body`, async () => {
      await withBrain(databaseUrl, reverseWrite, async b => {
        b.writeFirstRunFile();
        const result = await expectUnitNotAborted(() => b.run());
        expect({ written: result.written, held: result.held }).toEqual({ written: 1, held: [] });
        expect({ v1: b.file().includes(V1), v2: b.file().includes(V2) }).toEqual({ v1: true, v2: true });
      });
    }, 180_000);

    test(`${id} write-through off: no file is written or replaced`, async () => {
      await withBrain(databaseUrl, reverseWrite, async b => {
        await b.engine.setConfig('sync.write_through', 'false');
        _resetWriteThroughCacheForTest();
        const before = b.writeFirstRunFile();
        const result = await expectUnitNotAborted(() => b.run());
        expect({ written: result.written, held: result.held, file: b.file() === before }).toEqual({ written: 0, held: [], file: true });
      });
    }, 180_000);

    test(`${id} storage.db_only: a page in a db_only directory gets no file`, async () => {
      await withBrain(databaseUrl, reverseWrite, async b => {
        writeFileSync(join(b.root, 'gbrain.yml'), 'storage:\n  db_only:\n    - wiki/originals\n');
        const result = await expectUnitNotAborted(() => b.run());
        expect({ written: result.written, file: existsSync(b.path) }).toEqual({ written: 0, file: false });
      });
    }, 180_000);

    test(`${id} recorded source_path: the file of record is written and no slug-named twin appears`, async () => {
      await withBrain(databaseUrl, reverseWrite, async b => {
        await b.engine.executeRaw('UPDATE pages SET source_path = $1 WHERE source_id = $2 AND slug = $3', ['Ideas/Alice Example idea.md', SOURCE, DREAM_SLUG]);
        const recorded = join(b.root, 'Ideas/Alice Example idea.md');
        const result = await expectUnitNotAborted(() => b.run());
        expect({ written: result.written, recorded: existsSync(recorded) && b.file(recorded).includes(V2), twin: existsSync(b.path) })
          .toEqual({ written: 1, recorded: true, twin: false });
      });
    }, 180_000);

    test(`${id} concurrent file edit after the comparison: the editor's bytes survive and the page is held`, async () => {
      await withBrain(databaseUrl, reverseWrite, async b => {
        b.writeFirstRunFile();
        const edited = `${b.file()}\n${LATE_EDIT}\n`;
        const racing = editsAfterComparison(b.engine, () => writeFileSync(b.path, edited));
        const result = await expectUnitNotAborted(() => b.run(racing));
        expect({ written: result.written, held: heldFor(result.held).length, file: b.file() === edited }).toEqual({ written: 0, held: 1, file: true });
      });
    }, 180_000);

    test(`${id} file edit while the replacement is staged: the editor's bytes survive, the staged file is removed and the page is held`, async () => {
      await withBrain(databaseUrl, reverseWrite, async b => {
        b.writeFirstRunFile();
        const edited = `${b.file()}\n${LATE_EDIT}\n`;
        const realWrite = fs.writeFileSync;
        let landed = false;
        const staging = spyOn(fs, 'writeFileSync').mockImplementation(((path: fs.PathOrFileDescriptor, ...rest: unknown[]) => {
          if (!landed && String(path).startsWith(`${b.path}.`) && String(path).endsWith('.tmp')) { realWrite(b.path, edited); landed = true; }
          return (realWrite as (...a: unknown[]) => void)(path, ...rest);
        }) as typeof fs.writeFileSync);
        let result: { written: number; held: string[] };
        try { result = await expectUnitNotAborted(() => b.run()); } finally { staging.mockRestore(); }
        expect(landed).toBe(true);
        expect({ written: result.written, held: heldFor(result.held).length, file: b.file() === edited,
          staged: readdirSync(dirname(b.path)).filter(name => name.endsWith('.tmp')) }).toEqual({ written: 0, held: 1, file: true, staged: [] });
      });
    }, 180_000);

    test(`${id} control, no file yet: the page's file is written`, async () => {
      await withBrain(databaseUrl, reverseWrite, async b => {
        const result = await expectUnitNotAborted(() => b.run());
        expect({ written: result.written, held: result.held, v2: existsSync(b.path) && b.file().includes(V2) }).toEqual({ written: 1, held: [], v2: true });
      });
    }, 180_000);
  });
}