Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.1 KB
Raw Blame
/**
 * Foundations 2 (Lane C) attribution for the remaining unmanaged writers: the
 * captured-facts and extractor-facts repairs, the calibration wave undo, the
 * legacy sync soft delete (`softDeleteSyncPages`), capture ingest tombstones,
 * extraction review promote and reject, and the conversation fact index's
 * derived fact writes (`writeDerivedFacts`) run in maintenanceTransaction.
 * Pages they advance name the local maintenance principal; rows they change
 * keep their creator and move their last writer.
 *
 * Protects the remaining writer families in docs/architecture/system-of-record.md.
 * Fails if any of those writers runs outside maintenanceTransaction. Runs on
 * PGLite, and on Postgres (direct and transaction-mode PgBouncer) through
 * test/e2e/write-attribution-postgres.test.ts.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { createHash } from 'node:crypto';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { operationsByName } from '../src/core/operations.ts';
import { runRepairCommand } from '../src/commands/repair.ts';
import { undoWave } from '../src/core/calibration/undo-wave.ts';
import { softDeleteSyncPages } from '../src/core/company-brain/profile.ts';
import { makeIngestCaptureHandler } from '../src/core/minions/handlers/ingest-capture.ts';
import { writeDerivedFacts } from '../src/core/persistence/derived-facts.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { configureGateway, resetGateway } from '../src/core/ai/gateway.ts';
import { LEGACY_EMBEDDING_CONFIG } from './helpers/legacy-embedding-config.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { withEnv } from './helpers/with-env.ts';
import { CREATOR_ACTOR, asCreator, revisionActor, rowActors, unmanagedBrain, type Actor, type UnmanagedBrain } from './helpers/unmanaged-attribution.ts';

const engines: BrainEngine[] = [];
const scratch = mkdtempSync(join(tmpdir(), 'gbrain-write-attribution-misc-'));
let closePostgres: (() => Promise<void>) | undefined;

beforeAll(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); closePostgres = pg.close;
  }
}, 120_000);
afterAll(async () => {
  resetGateway(); // R5: restore the preload baseline for later files in this shard
  for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
  await closePostgres?.();
  rmSync(scratch, { recursive: true, force: true });
});

const actors = (rows: Array<{ id: number; created: Actor; last: Actor }>) => rows.map(({ created, last }) => ({ created, last }));
const ctx = (brain: UnmanagedBrain): OperationContext => ({ engine: brain.engine, config: { engine: brain.engine.kind } as never,
  logger: { info() {}, warn() {}, error() {} } as never, dryRun: false, remote: false, sourceId: brain.sourceId });
async function creatorPage(brain: UnmanagedBrain, slug: string, frontmatter: Record<string, unknown> = {}) {
  return asCreator(brain.engine, tx => tx.putPage(slug, { type: 'note', title: slug, compiled_truth: 'A page body.', frontmatter }, { sourceId: brain.sourceId }));
}
const deletedRevisionActor = async (brain: UnmanagedBrain, slug: string) => (await brain.engine.executeRaw<Actor>(
  `SELECT revision_write_request_id::text AS request, revision_principal_kind AS kind, revision_principal_id AS id
     FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NOT NULL`, [brain.sourceId, slug]))[0];
async function repair(engine: BrainEngine, kind: string, args: string[]) {
  const lines: string[] = [];
  const original = console.log;
  console.log = (...parts: unknown[]) => { lines.push(parts.map(String).join(' ')); };
  try { await runRepairCommand(engine, [kind, ...args, '--json']); } finally { console.log = original; }
  return JSON.parse(lines.join('\n')).results[0] as { apply_command: string; outcomes?: Record<string, number> };
}
const expectHash = (preview: { apply_command: string }) => preview.apply_command.match(/--expect ([0-9a-f]+)/)![1];

describe('remaining unmanaged writers', () => {
  test('gbrain repair captured-facts --apply expires a database-only self-capture row, keeping its creator', async () => {
    const claude = join(scratch, 'claude');
    mkdirSync(join(claude, 'projects', '-tmp-gbrain-claude-cli-cwd-4242'), { recursive: true });
    writeFileSync(join(claude, 'projects', '-tmp-gbrain-claude-cli-cwd-4242', 'sess-self.jsonl'), '{}\n');
    for (const engine of engines) {
      const brain = await unmanagedBrain(engine);
      await asCreator(engine, tx => tx.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source, source_session)
        VALUES ($1, 'people/alice-example', 'Alice Example drinks oat milk', 'fact', 'private', 'hook:writeback', 'sess-self')`, [brain.sourceId]));
      await withEnv({ CLAUDE_CONFIG_DIR: claude }, async () => {
        const preview = await repair(engine, 'captured-facts', ['--source', brain.sourceId]);
        expect((await repair(engine, 'captured-facts', ['--source', brain.sourceId, '--apply', '--expect', expectHash(preview)])).outcomes).toEqual({ expired: 1 });
      });
      expect(actors(await rowActors(engine, 'facts', 'source_id=$1', [brain.sourceId]))).toEqual([{ created: CREATOR_ACTOR, last: brain.maintenance }]);
    }
  }, 120_000);

  test('gbrain repair extractor-facts --apply restores an expired extractor fact, keeping its creator', async () => {
    for (const engine of engines) {
      const brain = await unmanagedBrain(engine);
      await creatorPage(brain, 'conversations/example-call');
      await asCreator(engine, tx => tx.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source, source_session, row_num, source_markdown_slug, expired_at)
        VALUES ($1, 'people/alice-example', 'Alice sends the deck', 'commitment', 'private', 'cli:extract-conversation-facts:sess', 'sess', NULL, 'conversations/example-call', now())`,
      [brain.sourceId]));
      const preview = await repair(engine, 'extractor-facts', ['--source', brain.sourceId, '--include-ambiguous']);
      expect((await repair(engine, 'extractor-facts', ['--source', brain.sourceId, '--include-ambiguous', '--apply', '--expect', expectHash(preview)])).outcomes)
        .toEqual({ restored: 1 });
      expect(actors(await rowActors(engine, 'facts', 'source_id=$1', [brain.sourceId]))).toEqual([{ created: CREATOR_ACTOR, last: brain.maintenance }]);
    }
  }, 120_000);

  test('a calibration wave undo keeps the take creator and moves its last writer', async () => {
    for (const engine of engines) {
      const brain = await unmanagedBrain(engine);
      const page = await creatorPage(brain, 'people/kai-example');
      const wave = `wave-${brain.sourceId}`;
      await asCreator(engine, async tx => {
        await tx.addTakesBatch([{ page_id: page.id, row_num: 1, claim: 'Ships on time', kind: 'bet', holder: 'world', weight: 0.7 }]);
        await tx.executeRaw(`UPDATE takes SET resolved_at=now(), resolved_quality='correct', resolved_outcome=true, resolved_by='gbrain:grade_takes' WHERE page_id=$1`, [page.id]);
      });
      const [take] = await engine.executeRaw<{ id: number }>('SELECT id::int AS id FROM takes WHERE page_id=$1', [page.id]);
      await engine.executeRaw(`INSERT INTO take_grade_cache (take_id, prompt_version, judge_model_id, evidence_signature, verdict, confidence, applied, wave_version)
        VALUES ($1, 'v1', 'test:judge', 'sig', 'correct', 0.99, true, $2)`, [take.id, wave]);
      expect((await undoWave(engine, { waveVersion: wave })).resolutions_reverted).toBe(1);
      expect(actors(await rowActors(engine, 'takes', 'page_id=$1', [page.id]))).toEqual([{ created: CREATOR_ACTOR, last: brain.maintenance }]);
    }
  }, 120_000);

  test('the legacy sync soft delete and a capture tombstone advance their pages under the maintenance principal; an extraction review is a page-door write attributed to its request', async () => {
    for (const engine of engines) {
      const brain = await unmanagedBrain(engine);
      await creatorPage(brain, 'notes/sync-removed-example');
      expect(await softDeleteSyncPages(engine, ['notes/sync-removed-example'], { sourceId: brain.sourceId })).toEqual(['notes/sync-removed-example']);
      expect(await deletedRevisionActor(brain, 'notes/sync-removed-example')).toEqual(brain.maintenance);

      await creatorPage(brain, 'captures/tombstoned-example');
      const ingest = makeIngestCaptureHandler(engine);
      const result = await ingest({ data: { event: { source_id: brain.sourceId, source_kind: 'webhook', source_uri: 'test://tombstone', received_at: new Date().toISOString(),
        content_type: 'text/markdown', content: 'deleted', content_hash: createHash('sha256').update('deleted').digest('hex'), kind: 'tombstone', untrusted_payload: false, slug: 'captures/tombstoned-example' } } } as never);
      expect(result.status).toBe('deleted');
      expect(await deletedRevisionActor(brain, 'captures/tombstoned-example')).toEqual(brain.maintenance);

      const unverified = { provenance: 'auto-extracted', status: 'unverified' };
      await creatorPage(brain, 'people/promoted-example', unverified);
      await creatorPage(brain, 'people/rejected-example', unverified);
      const review = operationsByName['extraction_review']!;
      await review.handler(ctx(brain), { action: 'promote', slugs: ['people/promoted-example'] });
      await review.handler(ctx(brain), { action: 'reject', slugs: ['people/rejected-example'] });
      const doorActor = { ...brain.maintenance, request: expect.stringMatching(/^[0-9a-f-]{36}$/) };
      expect(await revisionActor(engine, brain.sourceId, 'people/promoted-example')).toEqual(doorActor);
      expect(await deletedRevisionActor(brain, 'people/rejected-example')).toEqual(doorActor);
    }
  }, 120_000);

  test('the conversation fact index writes derived facts under the maintenance principal on an unmanaged brain', async () => {
    for (const engine of engines) {
      const brain = await unmanagedBrain(engine);
      await creatorPage(brain, 'conversations/derived-example');
      const inserted = await writeDerivedFacts(engine, brain.sourceId, 'conversations/derived-example', db => db.insertFacts([{ fact: 'Bob books the venue',
        kind: 'commitment', entity_slug: 'people/bob-example', visibility: 'private', source: 'cli:extract-conversation-facts:sess', row_num: 1,
        source_markdown_slug: 'conversations/derived-example' } as never], { source_id: brain.sourceId }));
      expect(inserted.inserted).toBe(1);
      expect(actors(await rowActors(engine, 'facts', 'source_id=$1', [brain.sourceId]))).toEqual([{ created: brain.maintenance, last: brain.maintenance }]);
    }
  }, 120_000);
});