Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
16.3 KB
Raw Blame
/**
 * LPH (a): `gbrain repair segmented-mirror` re-mirrors the canonical file of a page stored in segments that an older
 * binary's withdrawal mirror passed by.
 *
 * 1. Protects: before v0.60.299.0 a purge or forget struck the row in a segmented page's segments but skipped its file
 *    (`page_body_segmented`), so the file kept the withdrawn row. The preview lists exactly the file-backed segmented
 *    pages whose file is such an older render (the mirror's own file/database check passes and the ledger still changes
 *    the file), with each file's SHA-256 and size beside the canonical render's, and a hash. It never lists a clean
 *    segmented page or an inline page, and it holds (never rewrites) a segmented file that also differs from the
 *    database for another reason (`file_database_drift`). `--apply --expect <hash>` rewrites each listed file through
 *    a withdrawal-mirror effect of its own receipted request: the file loses the row, is byte-identical to the page's
 *    `gbrain export` render, and the Git effect commits it. A second preview lists nothing; a second apply (the new
 *    hash, or the old one replayed) writes nothing. A hash no preview saved, or one whose file changed since, refuses
 *    with `preview_changed` before anything is admitted.
 * 2. Fails when: the kind does not exist (red before), the preview misses a stale file or lists a clean, inline or
 *    drifted one, the apply writes anything other than the export render, overwrites the drifted file, or a stale hash
 *    applies.
 * 3. PGLite always; PostgreSQL when DATABASE_URL is set. The older binary's on-disk state is modelled by writing each
 *    file's pre-withdrawal bytes back after the withdrawal committed and committing them to Git, which is exactly what
 *    the skipped mirror and Git walk left behind.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { createHash } from 'node:crypto';
import { readFileSync, writeFileSync } from 'node:fs';
import { randomUUID } from 'node:crypto';
import { OperationError } from '../../src/core/ops/contract.ts';
import { withVerifiedLocalRegistration } from '../../src/core/persistence/identity.ts';
import { resolveRepairScope, type RepairResult } from '../../src/core/repair/core.ts';
import { repairRunner } from '../../src/core/repair/registry.ts';
import { durableGitRepo, git, gitAsync } from '../helpers/git-publication.ts';
import { openTwinBrain, type TwinBrain } from '../helpers/segmented-twins.ts';
import { exported, fileOf, purge, settle } from '../helpers/segmented-withdrawal.ts';
import { withEnv } from '../helpers/with-env.ts';
import { pathologicalArms } from './harness.ts';

const STALE_PURGE = 'people/stale-purge-example';
const STALE_FORGET = 'people/stale-forget-example';
const CLEAN = 'people/clean-example';
const DRIFT = 'people/drift-example';
const INLINE = 'people/inline-example';
const SEGMENTED = [STALE_PURGE, STALE_FORGET, CLEAN, DRIFT];
const CLAIM: Record<string, string> = {
  [STALE_PURGE]: 'Mirror Example locker code is 4411', [STALE_FORGET]: 'Mirror Example bike lock is 4412', [CLEAN]: 'Mirror Example vault code is 4413',
  [DRIFT]: 'Mirror Example safe code is 4414', [INLINE]: 'Mirror Example gate code is 4415',
};
const KEPT = 'Mirror Example adopted a narwhalbot';
const sha = (bytes: Buffer) => createHash('sha256').update(bytes).digest('hex');
const quiet = { info() {}, warn() {}, error() {} };

async function extract(brain: TwinBrain, slug: string, facts: string[]) {
  brain.setChatReply(JSON.stringify({ facts: facts.map(fact => ({ fact, kind: 'fact', entity: slug, confidence: 1, notability: 'high' })) }));
  expect(await brain.call('extract_facts', { turn_text: 'Synthetic meeting record. ' + facts.join('. ') + '.', visibility: 'world', valid_from: '2026-10-15T00:00:00Z' }, slug))
    .toMatchObject({ inserted: facts.length });
}

for (const { backend: kind } of pathologicalArms()) {
  describe(kind + ': gbrain repair segmented-mirror re-mirrors files an older binary left holding withdrawn rows', () => {
    let brain: TwinBrain;
    const before: Record<string, Buffer> = {};

    const run = (apply: boolean, expectHash?: string): Promise<RepairResult> => withEnv(brain.env(), () => withVerifiedLocalRegistration(brain.engine, brain.cli, async () => {
      const scope = await resolveRepairScope(brain.engine, brain.sourceId);
      const runner = await repairRunner(brain.engine, { apply, logger: quiet });
      return runner.run('segmented-mirror', scope, { explicit: true, sourceFlag: brain.sourceId, ...(expectHash ? { expect: expectHash } : {}) });
    }));
    const remirrorRequests = async () => (await brain.engine.executeRaw<{ n: number }>(
      "SELECT count(*)::int AS n FROM persistence_requests WHERE source_id=$1 AND operation='repair_segmented_mirror'", [brain.sourceId]))[0]!.n;
    const files = () => Object.fromEntries([...SEGMENTED, INLINE].map(slug => [slug, readFileSync(fileOf(brain, slug))]));

    beforeAll(async () => {
      brain = await openTwinBrain(kind, [INLINE], async seed => {
        await seed.setSwitch(false);
        await seed.put(INLINE, 1_100_000);
        await seed.setSwitch(true);
        for (const slug of SEGMENTED) await seed.put(slug, 1_100_000);
      });
      for (const slug of [...SEGMENTED, INLINE]) await extract(brain, slug, [CLAIM[slug]!, KEPT]);
      await settle(brain, kind);
      expect(await Promise.all([...SEGMENTED, INLINE].map(slug => brain.storageOf(slug)))).toEqual(['segmented', 'segmented', 'segmented', 'segmented', 'inline']);
      durableGitRepo(brain.root, [...SEGMENTED, INLINE].map(slug => slug + '.md'));

      // The older binary: each withdrawal committed in the database, and its file (and Git) kept the pre-withdrawal bytes.
      for (const slug of [...SEGMENTED, INLINE]) before[slug] = readFileSync(fileOf(brain, slug));
      for (const slug of [STALE_PURGE, CLEAN, DRIFT, INLINE]) await purge(brain, kind, slug, CLAIM[slug]!);
      const [forgotten] = await brain.engine.executeRaw<{ id: number }>('SELECT id FROM facts WHERE source_id=$1 AND source_markdown_slug=$2 AND fact=$3',
        [brain.sourceId, STALE_FORGET, CLAIM[STALE_FORGET]]);
      expect(await brain.call('forget_fact', { id: Number(forgotten!.id), request_id: randomUUID() }, STALE_FORGET)).toMatchObject({ state: 'committed' });
      await settle(brain, kind);
      for (const slug of [STALE_PURGE, STALE_FORGET, INLINE]) writeFileSync(fileOf(brain, slug), before[slug]!);
      // The drifted file also carries a local edit the database never saw.
      writeFileSync(fileOf(brain, DRIFT), before[DRIFT]!.toString('utf8').replace('00000007 acme-example journal line', '00000007 acme-example journal LINE edited by hand'));
      git(brain.root, 'add', '-A'); git(brain.root, 'commit', '-q', '-m', 'older binary state');
    }, 900_000);

    afterAll(() => brain.close(), 120_000);

    test('the seeded files are the older binary\'s: the withdrawn rows are still on disk though the database withdrew them', async () => {
      for (const slug of [STALE_PURGE, DRIFT, INLINE]) {
        expect(readFileSync(fileOf(brain, slug), 'utf8')).toContain(CLAIM[slug]!);
        expect(await brain.engine.executeRaw('SELECT 1 FROM facts WHERE source_id=$1 AND fact=$2', [brain.sourceId, CLAIM[slug]])).toEqual([]);
      }
      expect(readFileSync(fileOf(brain, STALE_FORGET)).equals(before[STALE_FORGET]!)).toBe(true);
      for (const slug of [STALE_PURGE, STALE_FORGET]) expect(readFileSync(fileOf(brain, slug)).equals(await exported(brain, slug))).toBe(false);
      expect(readFileSync(fileOf(brain, CLEAN), 'utf8')).not.toContain(CLAIM[CLEAN]!);
      expect(readFileSync(fileOf(brain, CLEAN)).equals(await exported(brain, CLEAN))).toBe(true);
    }, 300_000);

    test('preview lists exactly the stale segmented files, holds the drifted one and refuses a stale hash', async () => {
      const preview = await run(false);
      expect(preview.mode).toBe('dry_run');
      expect(preview.listing?.map(entry => entry.item)).toEqual([STALE_FORGET, STALE_PURGE].map(slug => `${brain.sourceId}:${slug}`));
      const stale = preview.details!.stale as Array<{ slug: string; path: string; file_sha256: string; file_bytes: number; expected_sha256: string; expected_bytes: number }>;
      for (const entry of stale) {
        const file = readFileSync(fileOf(brain, entry.slug)), render = await exported(brain, entry.slug);
        expect(entry).toMatchObject({ path: entry.slug + '.md', file_sha256: sha(file), file_bytes: file.length, expected_sha256: sha(render), expected_bytes: render.length });
      }
      expect((preview.details!.held as Array<{ slug: string; reason: string }>).map(entry => [entry.slug, entry.reason])).toEqual([[DRIFT, 'file_database_drift']]);
      expect(preview.preview_hash).toMatch(/^[0-9a-f]{64}$/);
      expect(preview.apply_command).toContain(`--apply --expect ${preview.preview_hash} --yes`);

      // A hash no preview saved refuses before anything is admitted.
      const unknown = await run(true, 'f'.repeat(64)).then(() => null, error => error);
      expect(unknown).toBeInstanceOf(OperationError);
      expect((unknown as OperationError).code).toBe('preview_changed');
      // So does the previewed hash once a listed file changed since the preview.
      const snapshot = files();
      writeFileSync(fileOf(brain, STALE_PURGE), Buffer.concat([snapshot[STALE_PURGE]!, Buffer.from('\n')]));
      const changed = await run(true, preview.preview_hash).then(() => null, error => error);
      writeFileSync(fileOf(brain, STALE_PURGE), snapshot[STALE_PURGE]!);
      expect(changed).toBeInstanceOf(OperationError);
      expect((changed as OperationError).code).toBe('preview_changed');
      expect(await remirrorRequests()).toBe(0);
      for (const [slug, bytes] of Object.entries(files())) expect({ slug, same: bytes.equals(snapshot[slug]!) }).toEqual({ slug, same: true });
    }, 600_000);

    test('apply rewrites each listed file to its export render through the mirror, commits it, and is idempotent', async () => {
      const preview = await run(false);
      const untouched = { [DRIFT]: readFileSync(fileOf(brain, DRIFT)), [INLINE]: readFileSync(fileOf(brain, INLINE)), [CLEAN]: readFileSync(fileOf(brain, CLEAN)) };
      const applied = await run(true, preview.preview_hash);
      expect(applied.outcomes).toEqual({ mirrored: 2 });
      expect(applied.applied).toBe(2);
      expect(await remirrorRequests()).toBe(2);
      await settle(brain, kind);
      for (const slug of [STALE_PURGE, STALE_FORGET]) {
        const file = readFileSync(fileOf(brain, slug));
        expect(file.equals(await exported(brain, slug))).toBe(true);
        expect(file.toString('utf8')).toContain(KEPT);
        expect((await gitAsync(brain.root, 'log', '-1', '--format=%s', '--', slug + '.md')).trim()).toBe(`gbrain: re-mirror segmented page ${slug}`);
        expect(await gitAsync(brain.root, 'status', '--porcelain', '--', slug + '.md')).toBe('');
      }
      expect(readFileSync(fileOf(brain, STALE_PURGE), 'utf8')).not.toContain(CLAIM[STALE_PURGE]!);
      for (const [slug, bytes] of Object.entries(untouched)) expect({ slug, same: readFileSync(fileOf(brain, slug)).equals(bytes) }).toEqual({ slug, same: true });

      // A second preview lists nothing; applying its hash, or replaying the first one, writes nothing.
      const again = await run(false);
      expect(again.listing).toEqual([]);
      expect((again.details!.held as Array<{ slug: string }>).map(entry => entry.slug)).toEqual([DRIFT]);
      const snapshot = files();
      const empty = await run(true, again.preview_hash);
      expect(empty.applied).toBe(0);
      const replay = await run(true, preview.preview_hash);
      expect(replay.applied).toBe(0);
      expect(replay.outcomes).toEqual({ replayed: 2 });
      expect(await remirrorRequests()).toBe(2);
      for (const [slug, bytes] of Object.entries(files())) expect({ slug, same: bytes.equals(snapshot[slug]!) }).toEqual({ slug, same: true });
    }, 600_000);
  });
  describe(kind + ': a segmented-mirror apply whose file changes before its mirror runs refuses with preview_changed', () => {
    let brain: TwinBrain;
    const PAGE = 'people/held-mirror-example';
    const HELD_CLAIM = 'Mirror Example locker code is 5511';
    const run = (apply: boolean, expectHash?: string, env: Record<string, string> = {}): Promise<RepairResult> => withEnv({ ...brain.env(), ...env }, () => withVerifiedLocalRegistration(brain.engine, brain.cli, async () => {
      const scope = await resolveRepairScope(brain.engine, brain.sourceId);
      const runner = await repairRunner(brain.engine, { apply, logger: quiet });
      return runner.run('segmented-mirror', scope, { explicit: true, sourceFlag: brain.sourceId, ...(expectHash ? { expect: expectHash } : {}) });
    }));

    beforeAll(async () => {
      brain = await openTwinBrain(kind, [], async seed => { await seed.setSwitch(true); await seed.put(PAGE, 1_100_000); });
      await extract(brain, PAGE, [HELD_CLAIM, KEPT]);
      await settle(brain, kind);
      expect(await brain.storageOf(PAGE)).toBe('segmented');
      durableGitRepo(brain.root, [PAGE + '.md']);
      const stale = readFileSync(fileOf(brain, PAGE));
      await purge(brain, kind, PAGE, HELD_CLAIM);
      writeFileSync(fileOf(brain, PAGE), stale);
      git(brain.root, 'add', '-A'); git(brain.root, 'commit', '-q', '-m', 'older binary state');
      // The owner's consumer is held: the repair's effects are inserted unclaimable until the test releases them.
      await brain.engine.executeRaw(`CREATE OR REPLACE FUNCTION lp_a_hold_remirror() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN
        IF EXISTS (SELECT 1 FROM persistence_requests r WHERE r.id=NEW.request_id AND r.operation='repair_segmented_mirror') THEN
          NEW.next_attempt_at := now() + interval '1 day'; END IF; RETURN NEW; END $$`);
      await brain.engine.executeRaw('CREATE TRIGGER lp_a_hold_remirror BEFORE INSERT ON persistence_effects FOR EACH ROW EXECUTE FUNCTION lp_a_hold_remirror()');
    }, 900_000);

    afterAll(() => brain.close(), 120_000);

    test('a formatting-only edit made while the mirror waits is refused, not overwritten', async () => {
      const preview = await run(false);
      expect(preview.listing?.map(entry => entry.item)).toEqual([`${brain.sourceId}:${PAGE}`]);
      const applied = await run(true, preview.preview_hash, { GBRAIN_WRITE_WAIT_MS: '500' });
      expect(applied.outcomes).toEqual({ mirror_queued: 1 });

      // A formatting-only edit: the quoted title parses the same, so the mirror's own drift check still passes.
      const original = readFileSync(fileOf(brain, PAGE), 'utf8');
      const edited = original.replace(/^title: Twin Example$/m, "title: 'Twin Example'");
      expect(edited).not.toBe(original);
      writeFileSync(fileOf(brain, PAGE), edited);
      const head = (await gitAsync(brain.root, 'rev-parse', 'HEAD')).trim();

      await brain.engine.executeRaw('DROP TRIGGER lp_a_hold_remirror ON persistence_effects');
      await brain.engine.executeRaw(`UPDATE persistence_effects SET next_attempt_at=now() WHERE source_id=$1 AND state='queued'`, [brain.sourceId]);
      await settle(brain, kind);

      expect(readFileSync(fileOf(brain, PAGE), 'utf8')).toBe(edited);
      expect((await gitAsync(brain.root, 'rev-parse', 'HEAD')).trim()).toBe(head);
      const [mirror] = await brain.engine.executeRaw<{ state: string; skipped: unknown }>(`SELECT e.state, e.data->'skipped' AS skipped FROM persistence_effects e
        JOIN persistence_requests r ON r.id=e.request_id WHERE r.operation='repair_segmented_mirror' AND e.kind='withdrawal-mirror'`);
      expect({ state: mirror!.state, skipped: typeof mirror!.skipped === 'string' ? JSON.parse(mirror!.skipped) : mirror!.skipped })
        .toEqual({ state: 'committed', skipped: [{ slug: PAGE, reason: 'preview_changed' }] });

      // Replaying the apply reports the typed refusal with the preview as its fix; a new preview lists the page again.
      const replay = await run(true, preview.preview_hash);
      const refused = replay.outcome_items?.find(entry => entry.item === `${brain.sourceId}:${PAGE}`);
      expect(refused).toMatchObject({ outcome: 'refused', reason: 'preview_changed' });
      expect((refused!.detail!.fix as { argv: string[] }).argv).toEqual(['gbrain', 'repair', 'segmented-mirror', '--source', brain.sourceId, '--json']);
      const again = await run(false);
      expect(again.listing?.map(entry => entry.item)).toEqual([`${brain.sourceId}:${PAGE}`]);
      expect(again.preview_hash).not.toBe(preview.preview_hash);
    }, 600_000);
  });
}