Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.4 KB
Raw Blame
/**
 * #6712 PR 0: `gbrain sync status --json` always carries `checkpoint_blockers` as an array, so the convergence
 * gate's status oracle (and an operator agent) can read it without guessing whether its absence means "nothing
 * blocks" or "not computed".
 *
 * Protects: the rendered JSON of `sync status --source <id> --json` (the command's own renderer,
 * `runSyncStatus`) has `checkpoint_blockers` as an array in all four states of a managed source: no cursor
 * (empty), an unfinished cursor before its checkpoint step (empty: no checkpoint is pending yet), a finished
 * cursor (empty), and a cursor at its checkpoint behind a receipt that still holds a publication recovery record
 * (that receipt, marked `recovery`). `cursors` stays an array in each.
 * Fails when: the field is left out for an absent, unfinished or finished cursor (master before this change
 * omitted it in all three).
 * #6712 PR 2 (L5): the blocker list is a heavy read a plain status skips; the array stays (empty) and
 * `checkpoint_blockers_read` says `not_read` with the --detail command, which lists the receipt. The fourth test pinned
 * the list on a plain status; it now asserts both reads.
 * PGLite in-memory; no production seam.
 */
import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { runSyncStatus } from '../src/commands/sync/operator.ts';
import { claimWorktree, getWorktreeBinding } from '../src/core/persistence/ownership.ts';
import { declarePersistenceProtocol } from '../src/core/persistence/protocol.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { withEnv } from './helpers/with-env.ts';

const SOURCE = 'shape-src';
let engine: PGLiteEngine;
let home: string;
let worktreeId: string;
let incarnation: string;

beforeAll(async () => {
  home = mkdtempSync(join(tmpdir(), 'gbrain-status-shape-'));
  engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema();
  const root = join(home, 'repo');
  mkdirSync(root);
  execFileSync('git', ['-C', root, 'init', '-q']);
  await withEnv({ GBRAIN_HOME: home }, async () => {
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    await engine.executeRaw('INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,\'{}\')', [SOURCE, root]);
    await claimWorktree(engine, SOURCE, root);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  });
  worktreeId = (await getWorktreeBinding(engine, SOURCE))!.worktree_id;
  incarnation = (await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [SOURCE]))[0]!.incarnation;
}, 60_000);
afterAll(async () => {
  await disposePersistenceConsumer(engine);
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  await engine.disconnect();
  rmSync(home, { recursive: true, force: true });
});
beforeEach(async () => {
  await engine.executeRaw("DELETE FROM op_checkpoints WHERE op='managed-sync'");
  await engine.executeRaw('DELETE FROM persistence_requests');
});

/** The JSON document `gbrain sync status --source <id> --json` prints. */
async function statusJson(...extra: string[]): Promise<Record<string, unknown>> {
  const lines: string[] = [];
  const log = console.log;
  console.log = (...args: unknown[]) => { lines.push(args.join(' ')); };
  try { await withEnv({ GBRAIN_SOURCE: undefined, GBRAIN_HOME: home }, () => runSyncStatus(engine, ['--source', SOURCE, '--json', ...extra])); } finally { console.log = log; }
  return JSON.parse(lines.join('\n')) as Record<string, unknown>;
}
async function cursor(header: Record<string, unknown>): Promise<string> {
  const runId = randomUUID();
  await engine.executeRaw(`INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES('managed-sync',$1,$2::text::jsonb)`, [`fp-${runId}`, JSON.stringify([{
    runId, sourceId: SOURCE, incarnation, target: 'a'.repeat(40), binding: { worktree_id: worktreeId }, ...header }])]);
  return runId;
}

describe('sync status --json checkpoint_blockers is always an array', () => {
  test('no cursor: an empty array', async () => {
    const status = await statusJson();
    expect(status.cursor).toBeNull();
    expect(status.checkpoint_blockers).toEqual([]);
    expect(status.cursors).toEqual([]);
  });

  test('an unfinished cursor before its checkpoint step: an empty array (no checkpoint is pending yet)', async () => {
    await cursor({ index: 1, total: 3, pending: { requestId: randomUUID(), intent: { kind: 'managed_sync_import', path: 'notes/two.md' } } });
    const status = await statusJson();
    expect(status.cursor).toMatchObject({ index: 1, total: 3, done: false });
    expect(status.checkpoint_blockers).toEqual([]);
    expect(Array.isArray(status.cursors)).toBe(true);
  });

  test('a finished cursor: an empty array', async () => {
    await cursor({ index: 3, total: 3, done: true });
    const status = await statusJson();
    expect(status.cursor).toMatchObject({ done: true });
    expect(status.checkpoint_blockers).toEqual([]);
    expect(Array.isArray(status.cursors)).toBe(true);
  });

  test('a cursor at its checkpoint behind a receipt that holds a recovery record: that receipt', async () => {
    const runId = randomUUID(), blocker = randomUUID();
    await engine.transaction(async tx => {
      await declarePersistenceProtocol(tx);
      await tx.executeRaw(`INSERT INTO persistence_requests(principal_kind,principal_id,request_id,operation,source_id,source_incarnation,slug,digest,authority,intent_bytes,
          terminal_reservation,state,error_code,error_message,recovery,intent,completed_at,updated_at,admitter_version,worktree_id)
        VALUES('local_cli','fixture',$1::uuid,'submit_job',$2,$3::uuid,'notes/two',$4,'{}'::jsonb,0,0,'failed','storage_error','x',$5::text::jsonb,$6::text::jsonb,
          now()-interval '1 hour',now()-interval '1 hour','0.60.243.0',$7::uuid)`,
      [blocker, SOURCE, incarnation, randomUUID(), JSON.stringify({ version: 1, path: '/nonexistent/x.md', root: '/nonexistent', beforeHash: null, afterHash: 'a' }),
        JSON.stringify({ kind: 'managed_sync_import', runId, index: 2 }), worktreeId]);
    });
    await engine.executeRaw(`INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES('managed-sync',$1,$2::text::jsonb)`, [`fp-${runId}`, JSON.stringify([{
      runId, sourceId: SOURCE, incarnation, index: 3, total: 3, target: 'a'.repeat(40), binding: { worktree_id: worktreeId },
      pending: { requestId: randomUUID(), intent: { kind: 'managed_sync_checkpoint' } } }])]);
    const plain = await statusJson();
    expect(plain.checkpoint_blockers).toEqual([]);
    expect(plain.checkpoint_blockers_read).toMatchObject({ status: 'not_read', fix: { next: 'run', argv: ['gbrain', 'sync', 'status', '--source', SOURCE, '--detail', '--json'] } });
    const status = await statusJson('--detail');
    expect(status.cursor).toMatchObject({ index: 3, total: 3, done: false });
    expect(status.checkpoint_blockers).toEqual([expect.objectContaining({ request_id: blocker, slug: 'notes/two', recovery: true, knock_on: false })]);
    expect(status.checkpoint_blockers_read).toEqual({ status: 'read' });
    expect(Array.isArray(status.cursors)).toBe(true);
  });
});