Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.7 KB
Raw Blame
/**
 * #5431 (W14 P1.8): a sync rename whose destination slug is already occupied.
 * Before, `updateSlug`'s unique violation was swallowed and the rename fell
 * back to import + soft-delete: the page's identity (versions, timeline,
 * edges, aliases, withdrawals) stayed on the soft-deleted row, a tombstone at
 * the destination was revived under a foreign id, and the stale `source_path`
 * exposed the live renamed page to the full-sync purge.
 *
 * Now the unique violation is classified. A tombstone destination is merged
 * in one maintenance transaction: the tombstone is re-keyed purge-style
 * (`<slug>~purged-<id>`, history retained, never hard-deleted) and the page
 * moves with its id; `source_path` is repaired in the same transaction. Any
 * other error fails the file without advancing the checkpoint. When the
 * rename still has to fall back to add semantics, `movePageIdReferences`
 * carries the page-id-keyed rows to the row that materialized, deduplicating
 * on the links composite key, before the stale row is soft-deleted.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { performSync } from '../src/commands/sync.ts';
import { movePageIdReferences } from '../src/core/page-state/rename-alias.ts';
import { maintenanceTransaction } from '../src/core/persistence/attribution.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';

const backends = testBackends();
const home = mkdtempSync(join(tmpdir(), 'gbrain-rename-collision-'));
const env = { GBRAIN_HOME: home, GBRAIN_SYNC_FAILURES_DIR: home };
const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
const person = (title: string, body: string, aliases: string[] = []) => `---\ntype: person\ntitle: ${title}\n${aliases.length ? `aliases: [${aliases.join(', ')}]\n` : ''}---\n\n${body}\n`;

for (const kind of backends) describe(`sync rename onto an occupied slug (${kind})`, () => {
  let engine: BrainEngine, close: (() => Promise<void>) | undefined;
  beforeAll(async () => {
    if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
    else { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); }
  }, 120_000);
  afterAll(async () => { await disposePersistenceConsumer(engine); if (close) await close(); else await engine.disconnect(); });

  async function fixture(run: (f: { source: string; root: string; sync: (opts?: Record<string, unknown>) => Promise<any> }) => Promise<void>) {
    const source = `rc-${randomUUID().replace(/-/g, '').slice(0, 12)}`, root = join(home, source);
    mkdirSync(join(root, 'people'), { recursive: true });
    git(root, 'init', '-q', '-b', 'main'); git(root, 'config', 'user.email', '[email protected]'); git(root, 'config', 'user.name', 'Example');
    writeFileSync(join(root, 'people', 'alice.md'), person('Alice', 'Alice is a person who [[people/carol]] knows.', ['Ali']));
    writeFileSync(join(root, 'people', 'carol.md'), person('Carol', 'Carol is a person.'));
    git(root, 'add', '-A'); git(root, 'commit', '-qm', 'initial');
    await engine.executeRaw("INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,'{}')", [source, root]);
    const sync = (opts: Record<string, unknown> = {}) => performSync(engine, { repoPath: root, sourceId: source, noPull: true, noEmbed: true, noExtract: true, concurrency: 1, ...opts });
    await withEnv(env, async () => { await sync(); await run({ source, root, sync }); });
  }
  const page = async (source: string, slug: string) => (await engine.executeRaw<{ id: number; deleted_at: string | null; source_path: string | null; compiled_truth: string }>(
    'SELECT id, deleted_at, source_path, compiled_truth FROM pages WHERE source_id=$1 AND slug=$2', [source, slug]))[0];
  const count = async (sql: string, params: unknown[]) => Number((await engine.executeRaw<{ n: number | string }>(sql, params))[0].n);

  /** Versions, timeline, a fact withdrawal and edges on a page: the identity a rename must carry (its declared alias comes from the file's frontmatter). */
  async function decorate(source: string, id: number, slug: string, peer: number) {
    await engine.executeRaw("INSERT INTO fact_withdrawals(source_id, visibility, subject, fact_hash) VALUES($1, 'private', $2, 'deadbeef') ON CONFLICT DO NOTHING", [source, slug]);
    await engine.executeRaw("INSERT INTO page_versions(page_id, compiled_truth, frontmatter) VALUES($1, 'older text', '{}'::jsonb)", [id]);
    await engine.executeRaw("INSERT INTO timeline_entries(page_id, date, source, summary) VALUES($1, '2024-01-02', 'test', $2)", [id, `${slug} met someone`]);
    await engine.executeRaw("INSERT INTO links(from_page_id, to_page_id, link_type, link_source) VALUES($1, $2, 'knows', 'test') ON CONFLICT DO NOTHING", [id, peer]);
    await engine.executeRaw("INSERT INTO links(from_page_id, to_page_id, link_type, link_source) VALUES($2, $1, 'knows', 'test') ON CONFLICT DO NOTHING", [id, peer]);
    await engine.executeRaw("INSERT INTO links(from_page_id, to_page_id, link_type, link_source, origin_page_id) VALUES($2, $2, 'self', 'test', $1) ON CONFLICT DO NOTHING", [id, peer]);
  }
  const identity = async (id: number) => ({
    versions: await count('SELECT count(*) AS n FROM page_versions WHERE page_id=$1', [id]),
    timeline: await count('SELECT count(*) AS n FROM timeline_entries WHERE page_id=$1', [id]),
    outbound: await count('SELECT count(*) AS n FROM links WHERE from_page_id=$1', [id]),
    inbound: await count('SELECT count(*) AS n FROM links WHERE to_page_id=$1', [id]),
    origin: await count('SELECT count(*) AS n FROM links WHERE origin_page_id=$1', [id]),
  });

  test('tombstone destination: merged in one transaction, tombstone re-keyed with its history, identity and source_path move with the page', () => fixture(async f => {
    const alice = await page(f.source, 'people/alice'), carol = await page(f.source, 'people/carol');
    await decorate(f.source, alice.id, 'people/alice', carol.id);
    await engine.putPage('people/bob', { type: 'person', title: 'Bob (old)', compiled_truth: 'an earlier bob' }, { sourceId: f.source });
    const bob = await page(f.source, 'people/bob');
    await engine.executeRaw("INSERT INTO page_versions(page_id, compiled_truth, frontmatter) VALUES($1, 'bob v1', '{}'::jsonb)", [bob.id]);
    await engine.executeRaw("INSERT INTO links(from_page_id, to_page_id, link_type, link_source) VALUES($1, $2, 'knows', 'test')", [bob.id, carol.id]);
    await engine.softDeletePages(['people/bob'], { sourceId: f.source });
    const before = await identity(alice.id);

    renameSync(join(f.root, 'people', 'alice.md'), join(f.root, 'people', 'bob.md'));
    git(f.root, 'add', '-A'); git(f.root, 'commit', '-qm', 'rename alice to bob');
    const result = await f.sync();
    expect(result.status).toBe('synced');

    const moved = await page(f.source, 'people/bob');
    expect(moved.id).toBe(alice.id);
    expect(moved.deleted_at).toBeNull();
    expect(moved.source_path).toBe('people/bob.md');
    expect(moved.compiled_truth).toContain('Alice is a person');
    expect(await page(f.source, 'people/alice')).toBeUndefined();
    const { versions, ...after } = await identity(alice.id);
    const { versions: versionsBefore, ...rest } = before;
    expect(after).toEqual(rest);
    expect(versions >= versionsBefore).toBe(true);
    expect(await engine.executeRaw('SELECT slug FROM page_aliases WHERE source_id=$1 AND alias_norm=$2', [f.source, 'ali'])).toEqual([{ slug: 'people/bob' }]);
    expect(await engine.executeRaw('SELECT subject FROM fact_withdrawals WHERE source_id=$1', [f.source])).toEqual([{ subject: 'people/bob' }]);
    expect(await count("SELECT count(*) AS n FROM slug_aliases WHERE source_id=$1 AND alias_slug='people/alice' AND canonical_slug='people/bob'", [f.source])).toBe(1);

    const tombstone = await page(f.source, `people/bob~purged-${bob.id}`);
    expect(tombstone.id).toBe(bob.id);
    expect(tombstone.deleted_at).not.toBeNull();
    expect(await count('SELECT count(*) AS n FROM page_versions WHERE page_id=$1', [bob.id])).toBe(1);
    expect(await count('SELECT count(*) AS n FROM links WHERE from_page_id=$1', [bob.id])).toBe(1);
    expect(await count('SELECT count(*) AS n FROM pages WHERE source_id=$1 AND deleted_at IS NULL', [f.source])).toBe(2);

    // The full-sync purge must not read the renamed page as a removed file.
    const full = await f.sync({ full: true });
    expect(['synced', 'first_sync']).toContain(full.status);
    expect((await page(f.source, 'people/bob')).deleted_at).toBeNull();
    expect(await count('SELECT count(*) AS n FROM pages WHERE source_id=$1 AND deleted_at IS NULL', [f.source])).toBe(2);
  }), 120_000);

  test('live destination: the add fallback carries the stale row\'s identity onto the destination row before soft-deleting it', () => fixture(async f => {
    const alice = await page(f.source, 'people/alice'), carol = await page(f.source, 'people/carol');
    await decorate(f.source, alice.id, 'people/alice', carol.id);
    await engine.putPage('people/bob', { type: 'person', title: 'Bob (live)', compiled_truth: 'a live bob' }, { sourceId: f.source });
    const bob = await page(f.source, 'people/bob');
    await engine.executeRaw("INSERT INTO links(from_page_id, to_page_id, link_type, link_source) VALUES($1, $2, 'knows', 'test')", [bob.id, carol.id]);
    const before = await identity(alice.id);

    renameSync(join(f.root, 'people', 'alice.md'), join(f.root, 'people', 'bob.md'));
    git(f.root, 'add', '-A'); git(f.root, 'commit', '-qm', 'rename alice onto a live bob');
    const result = await f.sync();
    expect(result.status).toBe('synced');

    const moved = await page(f.source, 'people/bob');
    expect(moved.id).toBe(bob.id);
    expect(moved.compiled_truth).toContain('Alice is a person');
    expect((await page(f.source, 'people/alice')).deleted_at).not.toBeNull();
    expect(await identity(alice.id)).toEqual({ versions: 0, timeline: 0, outbound: 0, inbound: 0, origin: 0 });
    const after = await identity(bob.id);
    expect(after.timeline).toBe(before.timeline);
    expect(after.outbound).toBe(before.outbound);
    expect(after.inbound).toBe(before.inbound);
    expect(after.origin).toBe(before.origin);
    expect(after.versions >= before.versions).toBe(true);
    expect(await engine.executeRaw('SELECT slug FROM page_aliases WHERE source_id=$1 AND alias_norm=$2', [f.source, 'ali'])).toEqual([{ slug: 'people/bob' }]);
    expect(await engine.executeRaw('SELECT subject FROM fact_withdrawals WHERE source_id=$1', [f.source])).toEqual([{ subject: 'people/bob' }]);
    expect(await engine.executeRaw('SELECT canonical_slug FROM slug_aliases WHERE source_id=$1 AND alias_slug=$2', [f.source, 'people/alice'])).toEqual([{ canonical_slug: 'people/bob' }]);
  }), 120_000);

  test('another SQLSTATE on the rename fails the file and leaves the checkpoint where it was', () => fixture(async f => {
    await engine.executeRaw(`CREATE OR REPLACE FUNCTION gbrain_test_refuse_slug() RETURNS trigger AS $$
      BEGIN IF NEW.slug = 'people/boom' THEN RAISE EXCEPTION 'injected rename failure' USING ERRCODE = 'P0001'; END IF; RETURN NEW; END $$ LANGUAGE plpgsql`);
    await engine.executeRaw('CREATE TRIGGER gbrain_test_refuse_slug BEFORE UPDATE OF slug ON pages FOR EACH ROW EXECUTE FUNCTION gbrain_test_refuse_slug()');
    try {
      const anchor = (await engine.executeRaw<{ last_commit: string | null }>('SELECT last_commit FROM sources WHERE id=$1', [f.source]))[0].last_commit;
      renameSync(join(f.root, 'people', 'alice.md'), join(f.root, 'people', 'boom.md'));
      git(f.root, 'add', '-A'); git(f.root, 'commit', '-qm', 'rename alice to boom');
      const result = await f.sync();
      expect(result.status).toBe('blocked_by_failures');
      expect(result.failedFiles).toBe(1);
      expect((await page(f.source, 'people/alice')).deleted_at).toBeNull();
      expect(await page(f.source, 'people/boom')).toBeUndefined();
      expect((await engine.executeRaw<{ last_commit: string | null }>('SELECT last_commit FROM sources WHERE id=$1', [f.source]))[0].last_commit).toBe(anchor);
    } finally {
      await engine.executeRaw('DROP TRIGGER IF EXISTS gbrain_test_refuse_slug ON pages');
      await engine.executeRaw('DROP FUNCTION IF EXISTS gbrain_test_refuse_slug()');
    }
    const result = await f.sync();
    expect(result.status).toBe('synced');
    expect((await page(f.source, 'people/boom')).compiled_truth).toContain('Alice is a person');
  }), 120_000);

  test('movePageIdReferences carries edges, timeline and versions to the surviving row and deduplicates on the links key', () => fixture(async f => {
    const alice = await page(f.source, 'people/alice'), carol = await page(f.source, 'people/carol');
    await engine.putPage('people/dup', { type: 'person', title: 'Dup', compiled_truth: 'the surviving row' }, { sourceId: f.source });
    const dup = await page(f.source, 'people/dup');
    await decorate(f.source, alice.id, 'people/alice', carol.id);
    await engine.executeRaw("INSERT INTO links(from_page_id, to_page_id, link_type, link_source) VALUES($1, $2, 'knows', 'test')", [dup.id, carol.id]);
    await engine.executeRaw("INSERT INTO timeline_entries(page_id, date, source, summary) VALUES($1, '2024-01-02', 'test', 'people/alice met someone')", [dup.id]);
    const total = await count('SELECT count(*) AS n FROM links', []);
    const from = await identity(alice.id), to = await identity(dup.id);

    await maintenanceTransaction(engine, tx => movePageIdReferences(tx, alice.id, dup.id));

    expect(await identity(alice.id)).toEqual({ versions: 0, timeline: 0, outbound: 0, inbound: 0, origin: 0 });
    const after = await identity(dup.id);
    expect(after.versions).toBe(from.versions + to.versions);
    expect(after.timeline).toBe(from.timeline + to.timeline - 1);
    expect(after.outbound).toBe(from.outbound + to.outbound - 1);
    expect(after.inbound).toBe(from.inbound + to.inbound);
    expect(after.origin).toBe(from.origin + to.origin);
    expect(await count('SELECT count(*) AS n FROM links', [])).toBe(total - 1);
    expect(await count('SELECT count(*) AS n FROM links WHERE from_page_id=$1 AND to_page_id=$2 AND link_type=$3', [dup.id, carol.id, 'knows'])).toBe(1);
  }), 120_000);
});