Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.9 KB
Raw Blame
/**
 * #6696 (A9): `gbrain repair receipt-compaction` compacts terminal receipts on
 * demand. `--older-than` is floored at the configured retention unless
 * `--force` (retention 90 days: a 30-day request is refused, and the refusal's
 * fix is the preview at the floor); failures stay unless
 * `--include-failures`; a receipt of a run whose sync cursor is open is never
 * compacted. Refusal -> preview -> apply -> verify through the fix objects; an
 * interrupted apply resumes; an admission racing the apply waits under 1 s.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { resolveRepairScope } from '../src/core/repair/core.ts';
import { repairRunner, repairSpec } from '../src/core/repair/registry.ts';
import { parseRepairArgs } from '../src/commands/repair.ts';
import { parseOlderThanHours } from '../src/core/repair/receipt-compaction.ts';
import type { WriteRequest } from '../src/core/persistence/model.ts';
import { editRequest, freshBrainFactory, requestFixture } from './helpers/persistence-request-fixture.ts';
import { testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';

const databaseUrl = process.env.DATABASE_URL;

test('flags parse with the purge-deleted duration grammar and belong to receipt-compaction only', () => {
  expect(parseRepairArgs(['receipt-compaction', '--older-than', '90d', '--include-failures', '--force'])).toMatchObject({ kind: 'receipt-compaction', olderThan: '90d', includeFailures: true, force: true });
  expect(() => parseRepairArgs(['receipt-compaction', '--older-than', '3w'])).toThrow(/hours \(72 or 72h\) or days \(30d\)/);
  expect(() => parseRepairArgs(['timeline', '--older-than', '30d'])).toThrow(/applies only to gbrain repair receipt-compaction/);
  expect([parseOlderThanHours('72'), parseOlderThanHours('72h'), parseOlderThanHours('30d'), parseOlderThanHours('x')]).toEqual([72, 72, 720, null]);
  expect(repairSpec('receipt-compaction')).toMatchObject({ explicit_only: true, preview_bound: true, consent: 'destructive' });
  expect(repairSpec('receipt-compaction').handler.publication).toBe('projection');
});

for (const kind of testBackends()) {
  describe(`receipt-compaction repair ${kind}`, () => {
    let factory: Awaited<ReturnType<typeof freshBrainFactory>>;
    let scratch: string;
    beforeAll(async () => {
      scratch = mkdtempSync(join(tmpdir(), 'gbrain-receipt-compaction-'));
      factory = await freshBrainFactory(kind, databaseUrl);
    }, 120_000);
    afterAll(async () => {
      await factory?.dispose();
      if (scratch) rmSync(scratch, { recursive: true, force: true });
    });

    test('refusal -> preview -> apply -> verify; failures and open sync runs kept; an interrupted apply resumes', () => withEnv({ GBRAIN_HOME: scratch, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
      const engine: BrainEngine = await factory.fresh();
      const requests = await requestFixture(engine);
      const terminal = async (slug: string, state: 'committed' | 'failed', days: number, intent?: Record<string, unknown>) => {
        const row = await requests.admit(slug);
        await editRequest(engine, row.id, `state=$2,completed_at=now()-($3::double precision*interval '1 day'),published_at=now(),claim_expires_at=NULL
          ${state === 'failed' ? ",error_code='source_changed',error_message='the file moved'" : ''}${intent ? ',intent=$4::text::jsonb' : ''}`,
        [state, days, ...(intent ? [JSON.stringify(intent)] : [])]);
        await engine.executeRaw('DELETE FROM persistence_effects WHERE request_id=$1::uuid', [row.id]);
        return row.id;
      };
      const old = await terminal('old', 'committed', 100);
      const month = await terminal('month', 'committed', 40);
      const failed = await terminal('failed', 'failed', 100);
      const open = await terminal('open-run', 'committed', 100, { kind: 'managed_sync_import', runId: 'run-open-example', content: 'x' });
      await engine.executeRaw(`INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES('managed-sync','cursor-example',$1::text::jsonb)`,
        [JSON.stringify([{ runId: 'run-open-example', done: false }])]);
      await engine.setConfig('persistence.receipt_retention_days', '90');
      const row = async (id: string) => (await engine.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE id=$1::uuid', [id]))[0]!;
      const bytes = async () => Number((await engine.executeRaw<{ n: string }>("SELECT terminal_bytes::text AS n FROM persistence_counters WHERE key='brain'"))[0]!.n);
      const scope = await resolveRepairScope(engine, undefined);
      const run = (apply: boolean, args: { olderThan?: string; force?: boolean; includeFailures?: boolean; expect?: string; limit?: number }) =>
        repairRunner(engine, { apply }).then(runner => runner.run('receipt-compaction', scope, { explicit: true, ...args }));

      // 30 days inside a 90-day retention: refused, and the fix is the preview at the floor.
      const refusal = await run(false, { olderThan: '30d' }).then(() => null, error => error);
      expect(refusal).toMatchObject({ code: 'invalid_params', fix: { argv: ['gbrain', 'repair', 'receipt-compaction', '--older-than', '90d', '--json'] } });
      const floor = await run(false, { olderThan: refusal.fix.argv[4] });
      expect(floor).toMatchObject({ affected: 1, residuals: { failures_kept: 1 }, cost: { lifetime_ids: 0, receipt_bytes: 0 } });
      expect(floor.sample).toEqual([`${requests.sourceId}:receipt:${(await row(old)).request_id}`]);
      expect((await run(false, { olderThan: '90d', includeFailures: true })).affected).toBe(2);

      // --force reaches inside the window; the apply is bound to the preview and resumes after an interruption.
      const preview = await run(false, { olderThan: '30d', force: true });
      expect(preview.affected).toBe(2);
      expect(preview.apply_command).toBe(`gbrain repair receipt-compaction --older-than 30d --force --apply --expect ${preview.preview_hash} --yes`);
      const before = await bytes();
      const reserved = Number((await row(old)).terminal_reservation) + Number((await row(month)).terminal_reservation);
      const first = await run(true, { olderThan: '30d', force: true, expect: preview.preview_hash, limit: 1 });
      expect(first).toMatchObject({ applied: 1, complete: false });
      const second = await run(true, { olderThan: '30d', force: true, expect: preview.preview_hash });
      expect(second).toMatchObject({ applied: 1, outcomes: { compacted: 1 } });
      expect(second.resumed_from).not.toBeNull();
      for (const id of [old, month]) expect(await row(id)).toMatchObject({ compacted: true, intent: null });
      for (const id of [failed, open]) expect((await row(id)).compacted).toBe(false);
      const kept = Number((await row(old)).terminal_reservation) + Number((await row(month)).terminal_reservation);
      expect(kept).toBeLessThan(reserved);
      expect(before - await bytes()).toBe(reserved - kept);
      // Verify: the same preview now finds nothing.
      expect((await run(false, { olderThan: '30d', force: true })).affected).toBe(0);
      // The open run's cursor finishes: its receipt becomes compactable.
      await engine.executeRaw("UPDATE op_checkpoints SET completed_keys=$1::text::jsonb WHERE op='managed-sync' AND fingerprint='cursor-example'",
        [JSON.stringify([{ runId: 'run-open-example', done: true }])]);
      expect((await run(false, { olderThan: '90d' })).affected).toBe(1);
    }), 120_000);

    test('an admission racing the apply waits under a second', () => withEnv({ GBRAIN_HOME: scratch, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
      const engine: BrainEngine = await factory.fresh();
      const requests = await requestFixture(engine);
      for (let i = 0; i < 40; i++) {
        const row = await requests.admit(`bulk-${i}`);
        await editRequest(engine, row.id, "state='committed',completed_at=now()-interval '60 days',published_at=now(),claim_expires_at=NULL");
        await engine.executeRaw('DELETE FROM persistence_effects WHERE request_id=$1::uuid', [row.id]);
      }
      const scope = await resolveRepairScope(engine, undefined);
      const preview = await (await repairRunner(engine, { apply: false })).run('receipt-compaction', scope, { explicit: true });
      expect(preview.affected).toBe(40);
      const apply = (await repairRunner(engine, { apply: true })).run('receipt-compaction', scope, { explicit: true, expect: preview.preview_hash });
      const latencies: number[] = [];
      for (let i = 0; i < 5; i++) {
        const started = performance.now();
        await requests.admit(`racing-${i}`);
        latencies.push(performance.now() - started);
      }
      expect((await apply).applied).toBe(40);
      expect(Math.max(...latencies)).toBeLessThan(1000);
    }), 120_000);
  });
}