Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.7 KB
Raw Blame
/**
 * #6712 PR 2 (L3): every `gbrain sync` flag is classified once, in `SYNC_FLAGS` (src/core/sync-flags.ts). The serve
 * ladder, its wire validator and the PGLite owner lane derive their allowlists from it.
 *
 * Protects:
 *   - every flag the sync argv parsers read is in the table, and every table flag is in the generated flag registry;
 *   - the three hand-offs agree with the table (a flag the table forwards is forwarded by each, one it routes to the
 *     client is accepted and never sent, everything else refuses);
 *   - a retired wire field (src/core/wire-skew.ts) is never sent by a newer client, and a newer resident accepts it
 *     from an older one, drops it and prints one notice naming it, on both hand-offs;
 *   - the PGLite owner lane accepts `--lanes N` and `--no-lanes` (it used to refuse them) without sending them.
 */
import { afterAll, beforeAll, expect, test } from 'bun:test';
import { readFileSync, mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { randomBytes, randomUUID } from 'node:crypto';
import type net from 'node:net';
import { SYNC_FLAGS, syncFlagsRouted, syncWireFields, type SyncFlagSpec } from '../src/core/sync-flags.ts';
import { WIRE_SKEW_WINDOWS, retiredWireFields } from '../src/core/wire-skew.ts';
import { CLI_FLAG_REGISTRY } from '../src/core/cli-flag-registry.generated.ts';
import { IGNORED_FLAGS, VALUE_FLAGS, WIRE_BOOL_FLAGS, maybeDelegateManagedSyncToServe, parseDelegatedSyncArgs } from '../src/commands/sync-delegate.ts';
import { DELEGATED_SYNC_OPTION_FIELDS, validateDelegatedSyncOptions } from '../src/core/context/sync-ipc.ts';
import { SYNC_BOOLEAN_FLAGS, SYNC_CLIENT_FLAGS, SYNC_VALUE_FLAGS, validateSyncWireParams } from '../src/core/persistence/sync-wire.ts';
import { parsePersistenceSyncArgs } from '../src/commands/sync-persistence-delegate.ts';
import { startResolveIpcServer } from '../src/core/context/resolve-ipc.ts';
import { localIpcSocketPath } from '../src/core/context/ipc-path.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { __resetDelegatedSyncForTests, startDelegatedSync } from '../src/core/serve-sync-runner.ts';
import type { SyncOpts } from '../src/commands/sync.ts';
import type { ConsumerRow } from '../src/core/persistence/consumer-heartbeat.ts';
import { withEnv } from './helpers/with-env.ts';

const flags = SYNC_FLAGS as Record<string, SyncFlagSpec>;
const retired = Object.values(WIRE_SKEW_WINDOWS).map(window => window.field);
let engine: PGLiteEngine;
const servers: net.Server[] = [];
const home = mkdtempSync(join(tmpdir(), 'gbrain-sync-flags-'));
beforeAll(async () => { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); }, 120_000);
afterAll(async () => {
  for (const server of servers) server.close();
  __resetDelegatedSyncForTests();
  await engine.disconnect();
  rmSync(home, { recursive: true, force: true });
});

test('every flag the sync argv parsers read is in the one table, and every table flag is in the flag registry', () => {
  const parsers = ['src/commands/sync/args.ts', 'src/commands/sync/run.ts'].map(path => readFileSync(path, 'utf8')).join('\n');
  const read = new Set([...parsers.matchAll(/args(?:\[i - 1\]|\[i\]|\[i\s*-\s*1\])?\s*(?:===|\.includes\(|\.indexOf\()\s*'(--[a-z][a-z-]*)'/g)].map(match => match[1]!));
  for (const match of parsers.matchAll(/args\.(?:includes|indexOf)\('(--[a-z][a-z-]*)'\)/g)) read.add(match[1]!);
  // `--retry-held` is refused by name with its own fix; `--help` is the router's.
  const unclassified = [...read].filter(flag => !(flag in flags) && !['--retry-held', '--help'].includes(flag));
  expect(read.size).toBeGreaterThan(25);
  expect(unclassified).toEqual([]);
  const registry = new Set(CLI_FLAG_REGISTRY.sync);
  expect(Object.keys(flags).filter(flag => !registry.has(flag))).toEqual([]);
});

test('the serve ladder, its wire validator and the owner lane are views of the table', () => {
  for (const [flag, spec] of Object.entries(flags)) {
    // Serve ladder: forward → on the wire (or fixed), client → accepted and not sent, refuse → refused by name.
    const argv = spec.arity === 'boolean' ? [flag] : [flag, flag === '--lanes' ? '4' : 'x'];
    const parsed = parseDelegatedSyncArgs(argv);
    if (spec.serve === 'refuse') expect(parsed).toEqual({ ok: false, refused: flag });
    else {
      expect(parsed.ok).toBe(true);
      const sent = parsed.ok ? Object.keys(parsed.options) : [];
      expect(sent).toEqual(spec.serve === 'forward' && spec.field ? [spec.field] : []);
      if (spec.serve === 'forward') expect(spec.field! in DELEGATED_SYNC_OPTION_FIELDS).toBe(true);
    }
    // Owner lane: forward → a wire field, client → consumed by the CLI, refuse → absent.
    const owner = spec.owner === 'forward' ? (spec.arity === 'boolean' ? SYNC_BOOLEAN_FLAGS[flag] : SYNC_VALUE_FLAGS[flag]) : undefined;
    expect(owner).toBe(spec.owner === 'forward' ? spec.field : undefined);
    expect(SYNC_CLIENT_FLAGS.has(flag)).toBe(spec.owner === 'client');
  }
  expect(Object.keys(WIRE_BOOL_FLAGS).sort()).toEqual(syncFlagsRouted('serve', 'forward').filter(flag => flags[flag].arity === 'boolean' && flags[flag].sets === undefined).sort());
  expect([...VALUE_FLAGS].sort()).toEqual(['--hard-deadline', '--lanes', '--source', '--timeout']);
  expect([...IGNORED_FLAGS].sort()).toEqual(['--json', '--no-delegate', '--no-hard-deadline', '--yes']);
  expect(Object.keys(syncWireFields('owner')).sort()).toEqual(['dryRun', 'exclude', 'full', 'includeGitignored', 'includeHidden', 'noBulk', 'noEmbed', 'noExtract',
    'noPull', 'noSchemaPack', 'repoPath', 'resetCheckpoint', 'retryFailed', 'skipFailed', 'sourceId', 'srcSubpath', 'strategy', 'workingTree']);
});

test('a retired wire field is never in the table and is accepted, dropped and named once by both residents', async () => {
  expect(retired).toContain('explicitProcessing');
  for (const field of retired) {
    expect(Object.values(flags).map(spec => spec.field)).not.toContain(field);
    expect(field in DELEGATED_SYNC_OPTION_FIELDS).toBe(false);
  }
  // Serve: accepted by shape, dropped, reported as ignored; a wrong shape still refuses.
  expect(validateDelegatedSyncOptions({ noPull: true, explicitProcessing: ['noEmbed'], timeoutSeconds: 5 }))
    .toEqual({ ok: true, options: { noPull: true, timeoutSeconds: 5 }, ignored: ['explicitProcessing'] });
  expect(validateDelegatedSyncOptions({ explicitProcessing: ['repoPath'], timeoutSeconds: 5 })).toEqual({ ok: false, error: 'invalid_options:explicitProcessing' });
  // Owner lane: the same window, the same drop.
  const wire = validateSyncWireParams({ options: { sourceId: 'notes', noPull: true, explicitProcessing: [] }, cwd: home, timeoutSeconds: 5 });
  expect(wire).toEqual({ options: { sourceId: 'notes', noPull: true }, cwd: home, timeoutSeconds: 5, ignored: ['explicitProcessing'] });
  expect(() => validateSyncWireParams({ options: { explicitProcessing: 'noEmbed' }, cwd: home, timeoutSeconds: 5 })).toThrow();
  expect([...retiredWireFields('owner').keys()]).toEqual([...retiredWireFields('serve').keys()]);
  // The serve prints one notice naming the field, its floor and its window.
  const lines: string[] = [];
  const write = process.stderr.write.bind(process.stderr);
  process.stderr.write = ((chunk: string) => { lines.push(String(chunk)); return true; }) as typeof process.stderr.write;
  // A runServe shutdown earlier in this process (another file) leaves the runner shutting down: start from a fresh runner.
  __resetDelegatedSyncForTests();
  try {
    const started = await startDelegatedSync(engine, { sourceId: 'missing-source', dryRun: true, explicitProcessing: ['noEmbed'], timeoutSeconds: 5 }, randomUUID());
    expect(started.ok).toBe(true);
  } finally { process.stderr.write = write; }
  const notices = lines.filter(line => line.includes('[gbrain notice]'));
  expect(notices).toHaveLength(1);
  expect(notices[0]).toContain('`explicitProcessing`');
  expect(notices[0]).toContain(WIRE_SKEW_WINDOWS.explicitProcessing.accept_until);
  __resetDelegatedSyncForTests();
});

test('a newer CLI never sends a retired field to the serve, whatever its options carry', async () => {
  const secret = randomBytes(32).toString('hex');
  const sock = localIpcSocketPath(join(mkdtempSync(join(home, 'sock-')), 'resolve.sock'));
  const received: Array<Record<string, unknown>> = [];
  const server = await startResolveIpcServer(sock, {
    resolve: async () => null,
    sync_start: (req: { options: unknown }) => { received.push(req.options as Record<string, unknown>); return { ok: false, protocol: 2, error: 'shutting_down' }; },
    sync_status: () => ({ ok: false, protocol: 2, error: 'unknown_job' }),
    sync_abort: () => ({ ok: true, protocol: 2 as const }),
  } as never, { secret });
  servers.push(server!);
  await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  const serve: ConsumerRow = { host_id: 'host', pid: 4242, nonce: 'n1', pid_ns: null, kind: 'serve', mode: 'full', started_at: new Date().toISOString(),
    renewed_at: new Date().toISOString(), restart_required: false, root_barrier_age_ms: null, pool: null, host_json_path: '/tmp/host.json', persistence_home: '/tmp',
    minted_under: null, version: 'test' };
  const err = console.error; console.error = () => {};
  const write = process.stderr.write.bind(process.stderr); process.stderr.write = (() => true) as typeof process.stderr.write;
  let outcome: unknown;
  try {
    outcome = await withEnv({ GBRAIN_HOME: home }, () => maybeDelegateManagedSyncToServe(engine, ['--source', 'notes', '--no-pull', '--no-embed'],
      { sourceId: 'notes', noPull: true, noEmbed: true, explicitProcessing: ['noEmbed'] } as unknown as SyncOpts,
      { config: { engine: 'postgres', database_url: 'postgresql://example.invalid/brain' }, probe: async () => serve, socket: async () => ({ sock, secret }), env: {} }));
  } finally { console.error = err; process.stderr.write = write; }
  expect(outcome).toMatchObject({ kind: 'own_consumer', reason: 'serve_refused' });
  expect(received).toHaveLength(1);
  expect(received[0]).toMatchObject({ sourceId: 'notes', noPull: true, noEmbed: true });
  for (const options of received) for (const field of retired) expect(field in options).toBe(false);
  for (const options of received) expect(Object.keys(options).every(key => key in DELEGATED_SYNC_OPTION_FIELDS)).toBe(true);
});

test('the PGLite owner lane accepts --lanes N and --no-lanes and never sends them', async () => {
  const params = await parsePersistenceSyncArgs(['--source', 'notes', '--no-pull', '--no-bulk', '--no-lanes', '--lanes', '4', '--hard-deadline', '13m', '--json'], home);
  expect(params.options).toEqual({ sourceId: 'notes', noPull: true, noBulk: true });
  await expect(parsePersistenceSyncArgs(['--source', 'notes', '--lanes'], home)).rejects.toMatchObject({ code: 'invalid_params' });
});