Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.4 KB
Raw Blame
/**
 * GST-2875: a remote `remember` that restates a confirmed private fact as world is stored private, with a proposal that
 * carries the widening, until the owner accepts it (the rule #9196 / GST-2511 applies to fence rows).
 *
 * 1. Protects: an agent that knows a private claim cannot publish it to every other connected client by remembering it.
 * 2. Fails when: the restated row is stored world, no proposal is filed, a remote recall returns the claim before the
 *    accept, the owner's accept does not make it world, or an ordinary remember (no private copy, a world copy, an
 *    explicit private visibility) changes.
 * 3. Real seams: MCP operation handlers with remote=true and a source-granted token; PGLite (Postgres when DATABASE_URL
 *    is set); managed and unmanaged.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
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 type { OperationContext } from '../src/core/ops/contract.ts';
import type { Principal } from '../src/core/persistence/model.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { operationsByName } from '../src/core/operations.ts';
import { mintLegacyToken } from '../src/core/token-mint.ts';
import { registerLocalWriter, readLocalWriter } from '../src/core/persistence/identity.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { withCoordinatedWrite, withTrustPromotion } from '../src/core/persistence/context.ts';
import { configureGateway, resetGateway } from '../src/core/ai/gateway.ts';
import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
import { decideTrustProposal } from '../src/core/trust/decide.ts';
import { listTrustProposals, parseTrustProposalRef } from '../src/core/trust/proposals.ts';
import { renderFactsTable } from '../src/core/facts-fence.ts';
import { LEGACY_EMBEDDING_CONFIG } from './helpers/legacy-embedding-config.ts';
import { heldProposalRef } from './helpers/held-proposal.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { readsUnscopedOnPurpose } from './helpers/reads-unscoped.ts';
import { withEnv } from './helpers/with-env.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';

const engines: BrainEngine[] = [];
const urls = new Map<BrainEngine, string>();
const home = mkdtempSync(join(tmpdir(), 'gbrain-open-facts-'));
let closePostgres: (() => Promise<void>) | undefined;
const quiet = { info() {}, warn() {}, error() {} };
/** Every fact the fixtures write is older than this instant (--created-before is required). */

beforeAll(async () => withEnv({ GBRAIN_HOME: home }, async () => {
  configureGateway({ ...LEGACY_EMBEDDING_CONFIG, env: {} });
  const lite = new PGLiteEngine(); await lite.connect({}); await lite.initSchema(); engines.push(lite);
  if (process.env.DATABASE_URL) {
    const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL);
    engines.push(pg.engine); urls.set(pg.engine, pg.databaseUrl); closePostgres = pg.close;
  }
}), 120_000);
afterAll(async () => {
  resetGateway();
  for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
  await closePostgres?.();
  rmSync(home, { recursive: true, force: true });
});

interface Brain { engine: BrainEngine; sourceId: string; remote: OperationContext; local: OperationContext }
/** A source on a shared-shaped brain (no owner, no members) with a token granted only that source. */
async function brain(engine: BrainEngine, managed: boolean): Promise<Brain> {
  const sourceId = `open-${randomUUID().slice(0, 8)}`;
  await disposePersistenceConsumer(engine);
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [sourceId]);
  await engine.setConfig('brain.audience', 'shared');
  await registerLocalWriter(engine, 'cli');
  const minted = await mintLegacyToken(engine, { name: `token-${sourceId}`, scopes: ['read', 'write'], sourceGrant: [sourceId], takesHolders: ['world'] });
  await readsUnscopedOnPurpose(engine, minted.id);
  if (managed) await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
  const base = { engine, config: { engine: engine.kind, embedding_disabled: true }, sourceId, dryRun: false, logger: quiet };
  await readLocalWriter(engine, 'cli');
  return {
    engine, sourceId,
    remote: { ...base, remote: true, transport: 'http', takesHoldersAllowList: ['world'],
      auth: { token: '', clientId: minted.id, principal: { kind: 'legacy_token', id: minted.id } as Principal, sourceId, allowedSources: [sourceId], scopes: ['read', 'write'] } },
    local: { ...base, remote: false },
  } as Brain;
}
const run = (ctx: OperationContext, op: string, params: Record<string, unknown>) =>
  operationsByName[op].handler(ctx, { request_id: randomUUID(), ...params }) as Promise<Record<string, any>>;

async function confirmFact(b: Brain, id: number) {
  await b.engine.transaction(tx => withCoordinatedWrite(tx, [b.sourceId], () => withTrustPromotion(tx, 'user_confirmed', () =>
    tx.executeRaw(`UPDATE facts SET trust_tier='user_confirmed' WHERE id=$1`, [id])), TEST_WRITE_ATTRIBUTION));
}
const owner = { confirmation: { via: 'tty' as const } };
const row = (n: number, claim: string, visibility = 'world') => ({ rowNum: n, claim, kind: 'fact', confidence: 1, visibility, notability: 'medium', active: true });
const body = (rows: ReturnType<typeof row>[]) => `Profile.\n\n## Facts\n\n${renderFactsTable(rows as never)}`;
const note = (title: string, text: string) => `---\ntype: note\ntitle: ${title}\n---\n${text}\n`;
const rowsOf = (b: Brain, claim: string) => b.engine.executeRaw<{ id: number; visibility: string; trust_tier: string; row_num: number | null; superseded_by: number | null }>(
  'SELECT id::int AS id, visibility, trust_tier, row_num, superseded_by::int AS superseded_by FROM facts WHERE source_id=$1 AND fact=$2 AND expired_at IS NULL ORDER BY id', [b.sourceId, claim]);
async function seeded(engine: BrainEngine, managed: boolean, slug: string, claim: string, confirm = true) {
  const b = await brain(engine, managed);
  await run(b.local, 'put_page', { slug, content: note(slug, body([row(1, 'Lives in Turin'), row(2, claim, 'private')])) });
  if (confirm) for (const r of await engine.executeRaw<{ id: number }>('SELECT id FROM facts WHERE source_id=$1 AND source_markdown_slug=$2', [b.sourceId, slug])) await confirmFact(b, Number(r.id));
  return b;
}
async function remoteSees(b: Brain, slug: string, claim: string) {
  __resetPrivateVisibilityCacheForTests();
  return JSON.stringify(await run(b.remote, 'recall', { entity: slug })).includes(claim);
}

describe('GST-2875: a remote remember restating a confirmed private claim', () => {
  for (const managed of [true, false]) {
    test(`is stored private with a widening proposal, hidden from remote reads, and the owner accept makes it world (${managed ? 'managed' : 'unmanaged'})`, async () => withEnv({ GBRAIN_HOME: home }, async () => {
      for (const engine of engines) {
        const slug = 'people/lia-example', claim = 'Lia Example keeps bees';
        const b = await seeded(engine, managed, slug, claim);
        const [confirmed] = await rowsOf(b, claim);
        const res = await run(b.remote, 'remember', { fact: claim, provenance: 'chat', entity: slug });
        expect(res.contested ?? res.outcome?.contested).toBeUndefined();
        const ref = await heldProposalRef(engine, b.sourceId, claim);
        expect(ref).toMatch(/^tp\d+$/);
        const rows = await rowsOf(b, claim);
        expect(rows.filter(r => r.visibility === 'world')).toEqual([]);
        expect(rows.find(r => r.id === confirmed!.id)).toMatchObject({ visibility: 'private', trust_tier: 'user_confirmed' });
        const restated = rows.find(r => r.id !== confirmed!.id)!;
        expect(restated).toMatchObject({ visibility: 'private', trust_tier: 'agent_written' });
        const proposal = (await listTrustProposals(engine, { status: 'pending' })).find(p => p.id === parseTrustProposalRef(ref)!);
        expect(proposal?.before_state.visibility).toEqual({ from: 'private', to: 'world' });
        expect(await remoteSees(b, slug, claim)).toBe(false);
        expect((await decideTrustProposal(engine, parseTrustProposalRef(ref)!, 'accept', owner)).status).toBe('accepted');
        expect((await rowsOf(b, claim)).find(r => r.id === restated.id)).toMatchObject({ visibility: 'world', trust_tier: 'user_confirmed' });
        expect(await remoteSees(b, slug, claim)).toBe(true);
      }
    }), 180_000);
  }

  test('a later page write keeps the held restatement private until the accept', async () => withEnv({ GBRAIN_HOME: home }, async () => {
    for (const engine of engines) {
      const slug = 'people/mae-example', claim = 'Mae Example keeps bees';
      const b = await seeded(engine, true, slug, claim);
      await run(b.remote, 'remember', { fact: claim, provenance: 'chat', entity: slug });
      await run(b.remote, 'remember', { fact: 'Mae Example likes tea', provenance: 'chat', entity: slug });
      expect((await rowsOf(b, claim)).map(r => r.visibility)).toEqual(['private', 'private']);
      expect(await remoteSees(b, slug, claim)).toBe(false);
    }
  }), 180_000);

  test('unchanged: no private copy, a world copy already present, or an explicit private remember', async () => withEnv({ GBRAIN_HOME: home }, async () => {
    for (const engine of engines) {
      const fresh = await seeded(engine, true, 'people/ned-example', 'Ned Example keeps bees');
      const plain = await run(fresh.remote, 'remember', { fact: 'Ned Example rides a bike', provenance: 'chat', entity: 'people/ned-example' });
      expect(plain.contested).toBeUndefined();
      expect((await rowsOf(fresh, 'Ned Example rides a bike')).map(r => r.visibility)).toEqual(['world']);

      const shared = await brain(engine, true);
      await run(shared.local, 'put_page', { slug: 'people/ola-example', content: note('Ola', body([row(1, 'Ola Example keeps bees')])) });
      for (const r of await engine.executeRaw<{ id: number }>('SELECT id FROM facts WHERE source_id=$1', [shared.sourceId])) await confirmFact(shared, Number(r.id));
      const again = await run(shared.remote, 'remember', { fact: 'Ola Example keeps bees', provenance: 'chat', entity: 'people/ola-example' });
      expect(again.contested).toBeUndefined();
      expect((await rowsOf(shared, 'Ola Example keeps bees')).map(r => r.visibility).every(v => v === 'world')).toBe(true);

      const kept = await seeded(engine, true, 'people/pia-example', 'Pia Example keeps bees');
      await run(kept.remote, 'remember', { fact: 'Pia Example keeps bees', provenance: 'chat', entity: 'people/pia-example', visibility: 'private' });
      expect((await rowsOf(kept, 'Pia Example keeps bees')).every(r => r.visibility === 'private')).toBe(true);
      expect((await listTrustProposals(engine, { status: 'pending' })).filter(p => (p.before_state as { visibility?: unknown }).visibility && p.source_id === kept.sourceId)).toEqual([]);
    }
  }), 180_000);
  test('the hold pairs with the private copy on the remembered entity, so the owner accept makes it world (review fix)', async () => withEnv({ GBRAIN_HOME: home }, async () => {
    for (const engine of engines) {
      const claim = 'Keeps bees on the roof';
      const b = await seeded(engine, true, 'people/ada-example', claim);
      await run(b.local, 'put_page', { slug: 'people/bo-example', content: note('Bo', body([row(1, 'Lives in Turin'), row(2, claim, 'private')])) });
      for (const r of await engine.executeRaw<{ id: number }>('SELECT id FROM facts WHERE source_id=$1 AND source_markdown_slug=$2', [b.sourceId, 'people/bo-example'])) await confirmFact(b, Number(r.id));
      const [other, mine] = await rowsOf(b, claim);
      const res = await run(b.remote, 'remember', { fact: claim, provenance: 'chat', entity: 'people/bo-example' });
      expect(res.contested).toBeUndefined();
      const ref = await heldProposalRef(engine, b.sourceId, claim);
      expect(ref).toMatch(/^tp\d+$/);
      const restated = (await rowsOf(b, claim)).find(r => r.id !== other!.id && r.id !== mine!.id)!;
      expect(restated.visibility).toBe('private');
      expect((await decideTrustProposal(engine, parseTrustProposalRef(ref)!, 'accept', owner)).status).toBe('accepted');
      expect((await rowsOf(b, claim)).find(r => r.id === restated.id)).toMatchObject({ visibility: 'world', trust_tier: 'user_confirmed' });
      expect((await rowsOf(b, claim)).find(r => r.id === other!.id)).toMatchObject({ visibility: 'private', trust_tier: 'user_confirmed' });
    }
  }), 180_000);

  test('a GST-2511 widening whose fence row was detached later is not applied by the accept (review fix)', async () => withEnv({ GBRAIN_HOME: home }, async () => {
    for (const engine of engines) {
      const slug = 'people/yan-example', claim = 'Yan Example keeps bees';
      const b = await seeded(engine, true, slug, claim);
      const current = await run(b.remote, 'get_page', { slug, include_content: true });
      const widened = await run(b.remote, 'put_page', { slug, content: note(slug, body([row(1, 'Lives in Turin'), row(3, claim)])), expected_revision: current.revision });
      expect(widened.contested).toBeUndefined();
      const widenedRef = await heldProposalRef(engine, b.sourceId, claim);
      expect(widenedRef).toMatch(/^tp\d+$/);
      const restated = (await rowsOf(b, claim)).find(r => r.trust_tier !== 'user_confirmed')!;
      expect(restated.visibility).toBe('private');
      // url-clone-fences keeps an appended row database-only before it restores the file.
      await engine.transaction(tx => withCoordinatedWrite(tx, [b.sourceId], () =>
        tx.executeRaw('UPDATE facts SET row_num = NULL, source_markdown_slug = NULL WHERE id = $1', [restated.id]), TEST_WRITE_ATTRIBUTION));
      await decideTrustProposal(engine, parseTrustProposalRef(widenedRef)!, 'accept', owner);
      expect((await rowsOf(b, claim)).find(r => r.id === restated.id)?.visibility).toBe('private');
    }
  }), 180_000);

  test('a database-only restatement (an entity with no page) is held and the owner accept makes it world', async () => withEnv({ GBRAIN_HOME: home }, async () => {
    for (const engine of engines) {
      const claim = 'Zoe Example ships on Fridays', entity = 'people/zoe-example';
      const b = await brain(engine, true);
      await engine.setConfig('sync.write_through', 'false');
      await run(b.local, 'remember', { fact: claim, provenance: 'chat', entity, visibility: 'private' });
      for (const r of await rowsOf(b, claim)) await confirmFact(b, r.id);
      const res = await run(b.remote, 'remember', { fact: claim, provenance: 'chat', entity });
      await engine.setConfig('sync.write_through', 'true');
      expect(res.contested).toBeUndefined();
      const ref = await heldProposalRef(engine, b.sourceId, claim);
      expect(ref).toMatch(/^tp\d+$/);
      const rows = await rowsOf(b, claim);
      const restated = rows.find(r => r.trust_tier === 'agent_written')!;
      expect(rows.map(r => r.row_num)).toEqual([null, null]);
      expect(restated.visibility).toBe('private');
      expect((await decideTrustProposal(engine, parseTrustProposalRef(ref)!, 'accept', owner)).status).toBe('accepted');
      expect((await rowsOf(b, claim)).find(r => r.id === restated.id)).toMatchObject({ visibility: 'world', trust_tier: 'user_confirmed' });
    }
  }), 180_000);
});