Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
39.8 KB
Raw Blame
import { afterAll, beforeAll, expect, test } from 'bun:test';
import { withGoogleAccount, sourceCursor, cursorOf } from './helpers/connector-fixture.ts';
import { randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { parseGitHubSourceConfig, runGitHubSync } from '../src/core/github-source.ts';
import { parseGoogleSourceConfig, runGoogleSync } from '../src/core/google/google-source.ts';
import { disposePersistenceConsumer, startPersistenceConsumer, waitForWrite } from '../src/core/persistence/service.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { registerLocalWriter, withVerifiedLocalRegistration } from '../src/core/persistence/identity.ts';
import { withSubmissionAuthority } from '../src/core/minions/submission-authority.ts';
import type { WriteRequest } from '../src/core/persistence/model.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { parseMarkdown } from '../src/core/markdown.ts';
import { withEnv } from './helpers/with-env.ts';
import { purgeStaleCheckpoints } from '../src/core/op-checkpoint.ts';
import { writeSingleFact } from '../src/core/facts/write-single.ts';
import { recordFactWithdrawal } from '../src/core/facts/withdrawal.ts';
import { withCoordinatedWrite } from '../src/core/persistence/context.ts';
import { prepareConnectorMutation } from '../src/core/persistence/connector-sync.ts';
import { publishMutation } from '../src/core/persistence/coordinator.ts';
import { claimNextWrite } from '../src/core/persistence/journal.ts';
import { localHostId } from '../src/core/persistence/identity.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
import { createConnectorFixture, options, json, googleConfig, githubConfig, contact, issueFixture, githubFetch, sourceCheckpoint, connectorPendingSet, withPausedOwnerBudget } from './helpers/connector-fixture.ts';

const { home, engines, env, source, boundSource, setup, teardown } = createConnectorFixture();
beforeAll(setup, 120_000);
afterAll(teardown);

test('public Google sync journals DB-only imports and repeat/restart checkpoints on both engines', async () => withEnv(env, async () => {
  for (const engine of engines) {
    const config = { kind: 'google', g_account: '[email protected]', g_services: 'contacts', g_access: 'env', g_token_env: 'CONNECTOR_TEST_TOKEN' };
    const f = await source(engine, config);
    const calls: string[] = [];
    const fetcher = async (url: string) => {
      calls.push(url);
      if (url.includes('/settings/sendAs')) return json({ sendAs: [] });
      if (url.includes('/people/me/connections')) return json({ connections: [{ resourceName: 'people/fixture-1', names: [{ displayName: 'Example Contact' }], emailAddresses: [{ value: '[email protected]' }] }], nextSyncToken: 'contacts-1' });
      throw new Error('Unexpected external fixture route');
    };
    const cfg = parseGoogleSourceConfig(config, f.dir);
    expect((await runGoogleSync(engine, f.id, cfg, options, withGoogleAccount(fetcher))).added).toBe(1);
    const pages = await engine.executeRaw<{ slug: string; source_path: string }>('SELECT slug,source_path FROM pages WHERE source_id=$1', [f.id]);
    expect(pages).toHaveLength(1);
    expect(existsSync(join(f.dir, pages[0].source_path))).toBe(false);
    const [receipt] = await engine.executeRaw<WriteRequest>("SELECT * FROM persistence_requests WHERE source_id=$1 AND intent->>'kind'='connector_v2_import' ORDER BY sequence LIMIT 1", [f.id]);
    expect(receipt.authority.databaseOnlyReason).toBe('connector_database');
    expect(receipt.outcome?.write_through).toEqual({ written: false, skipped: 'connector_database' });
    expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1 AND state<>\'committed\'', [f.id])).toHaveLength(0);
    await disposePersistenceConsumer(engine);
    expect((await runGoogleSync(engine, f.id, cfg, options, withGoogleAccount(fetcher))).added).toBe(0);
    expect(calls.some(url => url.includes('syncToken=contacts-1'))).toBe(true);
  }
}), 120_000);

test('public GitHub sync imports real pages without a Git cursor or filesystem publication', async () => withEnv(env, async () => {
  for (const engine of engines) {
    const config = { kind: 'github', gh_scope: 'repos', gh_repos: 'acme-example/app', gh_token_env: 'CONNECTOR_TEST_TOKEN' };
    const f = await source(engine, config);
    const issue = { number: 1, title: 'Example issue', state: 'open', body: 'A useful synthetic issue body.', created_at: '2026-01-01T00:00:00Z', updated_at: '2026-01-02T00:00:00Z', labels: [], assignees: [], user: { login: 'example-user' }, html_url: 'https://github.com/acme-example/app/issues/1' };
    const fetcher = async (url: string) => {
      const path = new URL(url).pathname;
      if (path.endsWith('/issues')) return json([issue]);
      if (path.endsWith('/pulls') || path.endsWith('/comments')) return json([]);
      if (path.endsWith('/issues/1')) return json(issue);
      if (path === '/repos/acme-example/app') return json({ full_name: 'acme-example/app', private: true, default_branch: 'main' });
      throw new Error('Unexpected external fixture route');
    };
    const cfg = parseGitHubSourceConfig(config, f.dir);
    const result = await runGitHubSync(engine, f.id, cfg, options, fetcher);
    expect(result.status).not.toBe('partial');
    expect((await engine.getPage('gh/acme-example/app/1', { sourceId: f.id }))?.compiled_truth).toContain('synthetic issue');
    expect(existsSync(join(f.dir, 'gh/acme-example/app/1.md'))).toBe(false);
    expect(await engine.executeRaw("SELECT fingerprint FROM op_checkpoints WHERE op='managed-sync'")).toHaveLength(0);
  }
}), 120_000);

test('Google pagination failure keeps the landed page and resumes at the failed one, never advancing the sync cursor; tombstones delete only the selected source', async () => withEnv(env, async () => {
  for (const engine of engines) {
    const f = await source(engine, googleConfig);
    let fail = true;
    let deleted = false;
    const listed: (string | null)[] = [];
    const fetcher = async (url: string) => {
      if (url.includes('/settings/sendAs')) return json({ sendAs: [] });
      const u = new URL(url);
      if (!u.searchParams.has('syncToken') && u.pathname.endsWith('/connections')) listed.push(u.searchParams.get('pageToken'));
      if (u.searchParams.has('syncToken')) return json({ connections: deleted ? [{ resourceName: 'people/first', metadata: { deleted: true } }] : [], nextSyncToken: 'contacts-next' });
      if (!u.searchParams.has('pageToken')) return json({ connections: [contact('first', 'First Example')], nextPageToken: 'second' });
      if (fail) return json({ error: { message: 'fixture pagination failure' } }, 400);
      return json({ connections: [contact('second', 'Second Example')], nextSyncToken: 'contacts-complete' });
    };
    const cfg = parseGoogleSourceConfig(googleConfig, f.dir);
    expect((await runGoogleSync(engine, f.id, cfg, options, withGoogleAccount(fetcher))).status).toBe('partial');
    // #8906: the page that landed stays, and the re-list resumes at the page that failed.
    expect(await engine.executeRaw('SELECT slug FROM pages WHERE source_id=$1', [f.id])).toEqual([{ slug: 'people/first-example' }]);
    expect(cursorOf(await sourceCheckpoint(engine, f.id)).flat().map(({ state }) => state?.contacts_sync_token ?? null)).toEqual([null]);
    fail = false;
    listed.length = 0;
    expect((await runGoogleSync(engine, f.id, cfg, options, withGoogleAccount(fetcher))).added).toBe(1);
    expect(listed).toEqual(['second']);
    expect((await engine.executeRaw<{ slug: string }>('SELECT slug FROM pages WHERE source_id=$1 ORDER BY slug', [f.id])).map((r) => r.slug)).toEqual(['people/first-example', 'people/second-example']);
    const other = await source(engine, googleConfig);
    expect((await runGoogleSync(engine, other.id, parseGoogleSourceConfig(googleConfig, other.dir), options, withGoogleAccount(fetcher))).added).toBe(2);
    deleted = true;
    const checkpoint = await sourceCheckpoint(engine, f.id);
    const executeRaw = engine.executeRaw;
    engine.executeRaw = async function (sql: string, params?: unknown[]) {
      if (sql.includes("frontmatter->>'google_contact_id'")) throw new Error('Synthetic identity lookup unavailable');
      return executeRaw.call(engine, sql, params);
    } as BrainEngine['executeRaw'];
    try {
      expect((await runGoogleSync(engine, f.id, cfg, options, withGoogleAccount(fetcher))).status).toBe('partial');
      expect(await sourceCheckpoint(engine, f.id)).toEqual(checkpoint);
    } finally { engine.executeRaw = executeRaw; }
    expect((await runGoogleSync(engine, f.id, cfg, options, withGoogleAccount(fetcher))).deleted).toBe(1);
    expect(await engine.getPage('people/first-example', { sourceId: f.id })).toBeNull();
    expect(await engine.getPage('people/first-example', { sourceId: other.id })).not.toBeNull();
  }
}), 120_000);

test('GitHub partial detail and pagination do not advance freshness or delete successfully imported pages', async () => withEnv(env, async () => {
  for (const engine of engines) {
    const f = await source(engine, githubConfig);
    const cfg = parseGitHubSourceConfig(githubConfig, f.dir);
    expect((await runGitHubSync(engine, f.id, cfg, options, githubFetch({ failDetail: true }))).status).toBe('partial');
    expect((await engine.getPage('gh/acme-example/app/1', { sourceId: f.id }))?.frontmatter.detail_fetched).toBe(false);
    // Fix wave 4: the partial run publishes the item's failure count, never a cursor.
    expect(await sourceCursor(engine, f.id)).toEqual([[{ state: { last_sweep_at: null, repos: [] } }]]);
    expect((await engine.executeRaw<{ last_sync_at: unknown }>('SELECT last_sync_at FROM sources WHERE id=$1', [f.id]))[0].last_sync_at).toBeNull();
    await disposePersistenceConsumer(engine);
    expect((await runGitHubSync(engine, f.id, cfg, options, githubFetch())).status).not.toBe('partial');
    const checkpoint = await sourceCheckpoint(engine, f.id);
    expect((await runGitHubSync(engine, f.id, cfg, { ...options, full: true }, githubFetch({ failSecondPage: true }))).status).toBe('partial');
    expect(await sourceCheckpoint(engine, f.id)).toEqual(checkpoint);
    expect(await engine.getPage('gh/acme-example/app/1', { sourceId: f.id })).not.toBeNull();
    expect((await runGitHubSync(engine, f.id, cfg, { ...options, githubItem: { repo: 'acme-example/app', number: 1, kind: 'issue', deleted: true } }, githubFetch())).deleted).toBe(1);
    expect(await engine.getPage('gh/acme-example/app/1', { sourceId: f.id })).toBeNull();
  }
}), 120_000);

test('remote, narrowed, and mismatched connector authority is refused before external requests', async () => withEnv(env, async () => {
  for (const engine of engines) {
    const f = await source(engine, githubConfig);
    const cfg = parseGitHubSourceConfig(githubConfig, f.dir);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    await importFromContent(engine, 'gh/acme-example/app/1', '---\ntitle: Private fixture\nvisibility: private\n---\nPrivate fixture content must remain untouched.\n', { sourceId: f.id, noEmbed: true });
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    const calls: string[] = [];
    const run = () => runGitHubSync(engine, f.id, cfg, options, githubFetch({ calls }));
    const stdio = await registerLocalWriter(engine, 'stdio');
    await expect(withVerifiedLocalRegistration(engine, stdio, run)).rejects.toMatchObject({ code: 'permission_denied' });
    await expect(withSubmissionAuthority({ version: 1, kind: 'remote_agent', principal: { kind: 'oauth_client', id: 'fixture-client' }, grant: { scopes: ['admin'], sourceId: f.id, sourceCreatedAt: new Date().toISOString(), allowedTools: ['submit_job'], allowedSlugPrefixes: ['*'] }, payloadHash: 'fixture' }, run)).rejects.toMatchObject({ code: 'permission_denied' });
    await expect(runGitHubSync(engine, f.id, { ...cfg, repos: ['foreign-example/app'] }, options, githubFetch({ calls }))).rejects.toMatchObject({ code: 'source_changed' });
    const cli = await registerLocalWriter(engine, 'cli');
    const [saved] = await engine.executeRaw<{ grant_ceiling: unknown }>('SELECT grant_ceiling FROM persistence_local_writers WHERE id=$1::uuid', [cli.id]);
    try {
      await engine.executeRaw("UPDATE persistence_local_writers SET grant_ceiling=jsonb_set(grant_ceiling,'{sourceIds}','[]'::jsonb) WHERE id=$1::uuid", [cli.id]);
      await expect(run()).rejects.toMatchObject({ code: 'permission_denied' });
    } finally { await engine.executeRaw('UPDATE persistence_local_writers SET grant_ceiling=$2::text::jsonb WHERE id=$1::uuid', [cli.id, JSON.stringify(saved.grant_ceiling)]); }
    expect(calls).toHaveLength(0);
    expect((await engine.getPage('gh/acme-example/app/1', { sourceId: f.id }))?.frontmatter.visibility).toBe('private');
    expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
    await run();
    expect((await engine.getPage('gh/acme-example/app/1', { sourceId: f.id }))?.frontmatter.visibility).toBe('private');
  }
}), 120_000);

test('managed connectors refuse unsupported dry runs and Git filters before credentials or external work', async () => withEnv(env, async () => {
  for (const engine of engines) for (const connector of ['google', 'github'] as const) {
    const config = connector === 'google' ? googleConfig : githubConfig;
    const f = await source(engine, config);
    let calls = 0;
    const fetcher = async () => { calls++; throw new Error('Unexpected external request'); };
    for (const mode of [{ dryRun: true }, { skipFailed: true }, { srcSubpath: 'scoped' },
      { exclude: ['private/**'] }, { includeHidden: ['.notes/**'] }, { includeGitignored: true }, { workingTree: true }, { strategy: 'code' as const }]) {
      const run = connector === 'google'
        ? runGoogleSync(engine, f.id, parseGoogleSourceConfig(config, f.dir), { ...options, ...mode }, withGoogleAccount(fetcher))
        : runGitHubSync(engine, f.id, parseGitHubSourceConfig(config, f.dir), { ...options, ...mode }, fetcher);
      await expect(run).rejects.toMatchObject({ code: 'invalid_params' });
    }
    expect(calls).toBe(0);
    expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
  }
}), 120_000);

test('source replacement after connector preflight cannot receive the old sweep on either engine', async () => withEnv(env, async () => {
  for (const engine of engines) for (const connector of ['google', 'github'] as const) {
    const config = connector === 'google' ? googleConfig : githubConfig;
    const f = await source(engine, config);
    let replaced = false;
    const fetcher = async (url: string) => {
      if (!replaced) {
        replaced = true;
        await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
        await engine.executeRaw('DELETE FROM sources WHERE id=$1', [f.id]);
        await engine.executeRaw('INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,$3::text::jsonb)', [f.id, f.dir, JSON.stringify(config)]);
        await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
      }
      if (connector === 'github') return githubFetch()(url);
      if (url.includes('/settings/sendAs')) return json({ sendAs: [] });
      return json({ connections: [contact('first', 'First Example')], nextSyncToken: 'stale-source-token' });
    };
    const run = connector === 'google'
      ? runGoogleSync(engine, f.id, parseGoogleSourceConfig(config, f.dir), options, withGoogleAccount(fetcher))
      : runGitHubSync(engine, f.id, parseGitHubSourceConfig(config, f.dir), options, fetcher);
    await expect(run).rejects.toMatchObject({ code: 'source_changed' });
    expect(await engine.executeRaw('SELECT slug FROM pages WHERE source_id=$1', [f.id])).toHaveLength(0);
    expect((await engine.executeRaw<{ last_sync_at: unknown }>('SELECT last_sync_at FROM sources WHERE id=$1', [f.id]))[0].last_sync_at).toBeNull();
  }
}), 120_000);

test('Google Gmail and Calendar ingest, fail without advancing, restart, and delete via the public entry', async () => withEnv(env, async () => {
  for (const engine of engines) {
    const config = { ...googleConfig, g_services: 'gmail,calendar' };
    const f = await source(engine, config);
    const cfg = parseGoogleSourceConfig(config, f.dir);
    const at = Math.floor(Date.now() / 1000) * 1000 - 60_000;
    const threadId = '17aa00000000a001';
    let delta = false;
    let fail = false;
    let removed = false;
    const fetcher = async (url: string) => {
      const u = new URL(url);
      if (url.includes('/settings/sendAs')) return json({ sendAs: [] });
      if (url.includes('/profile')) return json({ emailAddress: config.g_account, historyId: '100' });
      if (url.includes('/calendar/')) return json({ items: removed ? [{ id: 'example-event', status: 'cancelled' }] : [{ id: 'example-event', summary: 'Example planning', status: 'confirmed', start: { dateTime: new Date(at).toISOString() }, end: { dateTime: new Date(at + 3600_000).toISOString() } }], nextSyncToken: removed ? 'calendar-2' : 'calendar-1' });
      if (url.includes('/messages?')) {
        const q = u.searchParams.get('q') ?? '';
        const before = q.match(/before:(\d+)/)?.[1];
        return json({ messages: removed || before && Number(before) * 1000 <= at ? [] : [{ id: '17bb00000000a001', threadId }] });
      }
      if (url.includes('/history?')) return json({ historyId: delta ? '200' : '100', history: delta && !removed ? [{ messagesAdded: [{ message: { id: '17bb00000000a001', threadId } }] }] : [] });
      if (url.includes('/threads/')) {
        if (fail) return json({ error: { message: 'fixture unavailable' } }, 400);
        return json({ id: threadId, messages: [{ id: '17bb00000000a001', threadId, internalDate: String(at), labelIds: ['INBOX'], payload: { mimeType: 'text/plain', headers: [{ name: 'From', value: '[email protected]' }, { name: 'To', value: config.g_account }, { name: 'Subject', value: 'Example question' }], body: { data: Buffer.from('Could you review the example plan?').toString('base64url') } } }] });
      }
      throw new Error('Unexpected external fixture route');
    };
    const first = await runGoogleSync(engine, f.id, cfg, options, withGoogleAccount(fetcher));
    expect(first.status).not.toBe('partial');
    expect(first.added).toBe(2);
    const checkpoint = await sourceCheckpoint(engine, f.id);
    delta = true;
    fail = true;
    expect((await runGoogleSync(engine, f.id, cfg, options, withGoogleAccount(fetcher))).status).toBe('partial');
    expect(await sourceCursor(engine, f.id)).toEqual(cursorOf(checkpoint));
    fail = false;
    await disposePersistenceConsumer(engine);
    expect((await runGoogleSync(engine, f.id, cfg, options, withGoogleAccount(fetcher))).status).not.toBe('partial');
    removed = true;
    expect((await runGoogleSync(engine, f.id, cfg, { ...options, full: true }, withGoogleAccount(fetcher))).deleted).toBe(2);
    expect(await engine.executeRaw('SELECT slug FROM pages WHERE source_id=$1 AND deleted_at IS NULL', [f.id])).toHaveLength(0);
  }
}), 120_000);

test('paused connector owner returns one stable receipt and resident restart consumes its frozen import', async () => withEnv(env, async () => {
  for (const engine of engines) {
    const f = await source(engine, githubConfig);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    const binding = await claimWorktree(engine, f.id, f.dir);
    await engine.executeRaw("UPDATE persistence_worktrees SET state='draining' WHERE id=$1::uuid", [binding.worktree_id]);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    const cfg = parseGitHubSourceConfig(githubConfig, f.dir);
    const run = () => runGitHubSync(engine, f.id, cfg, options, githubFetch());
    // #5600: an accepted pending write is progress; the run ends partial with the receipt in its pending set.
    expect(await withPausedOwnerBudget(() => run())).toMatchObject({ status: 'partial', reason: 'writer_pending' });
    const [pending] = await connectorPendingSet(engine, f.id);
    expect(await withPausedOwnerBudget(() => run())).toMatchObject({ status: 'partial', reason: 'writer_pending' });
    expect((await connectorPendingSet(engine, f.id)).map(entry => entry.requestId)).toEqual([pending.requestId]);
    const rows = await engine.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE source_id=$1', [f.id]);
    expect(rows).toHaveLength(1);
    expect(await sourceCheckpoint(engine, f.id)).toHaveLength(0);
    await disposePersistenceConsumer(engine);
    await engine.executeRaw("UPDATE persistence_worktrees SET state='active' WHERE id=$1::uuid", [binding.worktree_id]);
    startPersistenceConsumer(engine, { engine: engine.kind });
    expect((await waitForWrite(engine, rows[0], { engine: engine.kind })).state).toBe('committed');
    expect(await engine.getPage('gh/acme-example/app/1', { sourceId: f.id })).not.toBeNull();
    expect(readFileSync(join(f.dir, 'gh/acme-example/app/1.md'), 'utf8')).toContain('synthetic issue');
  }
}), 120_000);

test('bound connector directories publish import, update, unchanged replay, and delete with their DB receipts', async () => withEnv(env, async () => {
  for (const engine of engines) for (const connector of ['google', 'github'] as const) {
    const config = connector === 'google' ? googleConfig : githubConfig;
    const f = await boundSource(engine, config);
    let body = 'Initial organization';
    let deleted = false;
    const fetcher = async (url: string) => {
      if (connector === 'github') {
        if (new URL(url).pathname.endsWith('/issues/1')) return json({ ...issueFixture, body });
        return githubFetch()(url);
      }
      if (url.includes('/settings/sendAs')) return json({ sendAs: [] });
      return json({ connections: deleted ? [{ resourceName: 'people/first', metadata: { deleted: true } }]
        : [{ ...contact('first', 'First Example'), organizations: [{ name: body }] }], nextSyncToken: 'contacts-bound' });
    };
    const run = () => connector === 'google'
      ? runGoogleSync(engine, f.id, parseGoogleSourceConfig(config, f.dir), options, withGoogleAccount(fetcher))
      : runGitHubSync(engine, f.id, parseGitHubSourceConfig(config, f.dir), { ...options, githubItem: { repo: 'acme-example/app', number: 1, kind: 'issue', deleted } }, fetcher);
    const slug = connector === 'google' ? 'people/first-example' : 'gh/acme-example/app/1';
    const path = join(f.dir, `${slug}.md`);
    expect((await run()).added).toBe(1);
    expect(readFileSync(path, 'utf8')).toContain(body);
    const [receipt] = await engine.executeRaw<WriteRequest>("SELECT * FROM persistence_requests WHERE source_id=$1 AND intent->>'kind'='connector_v2_import' ORDER BY sequence LIMIT 1", [f.id]);
    expect(receipt.outcome?.persistence).toEqual({ mode: 'filesystem', file_written: true, git_state: 'queued' });
    expect(receipt.authority.databaseOnlyReason).toBeUndefined();
    const first = readFileSync(path, 'utf8');
    await disposePersistenceConsumer(engine);
    expect((await run()).modified).toBe(0);
    expect(readFileSync(path, 'utf8')).toBe(first);
    body = 'Updated organization';
    expect((await run()).modified).toBe(1);
    const page = await engine.getPage(slug, { sourceId: f.id });
    expect(page).not.toBeNull();
    expect(parseMarkdown(readFileSync(path, 'utf8'), slug).compiled_truth).toBe(page!.compiled_truth);
    expect(readFileSync(path, 'utf8')).toContain(body);
    deleted = true;
    expect((await run()).deleted).toBe(1);
    expect(existsSync(path)).toBe(false);
    expect(await engine.getPage(slug, { sourceId: f.id })).toBeNull();
    expect((await run()).deleted).toBe(0);
  }
}), 120_000);

test('invalid bound connector roots refuse before any external request', async () => withEnv(env, async () => {
  for (const engine of engines) for (const invalid of ['source-root', 'physical-root', 'foreign-owner', 'lock-file'] as const) {
    const f = await boundSource(engine, githubConfig);
    const alternate = join(home, `alternate-${randomUUID()}`);
    mkdirSync(alternate);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    if (invalid === 'source-root') await engine.executeRaw('UPDATE sources SET local_path=$2 WHERE id=$1', [f.id, alternate]);
    else if (invalid === 'foreign-owner') await engine.executeRaw('UPDATE persistence_worktrees SET owner_host_id=$2::uuid WHERE id=$1::uuid', [f.binding.worktree_id, randomUUID()]);
    else if (invalid === 'lock-file') { renameSync(f.binding.coordination_path!, `${f.binding.coordination_path}-old`); mkdirSync(f.binding.coordination_path!); }
    else { renameSync(f.dir, `${f.dir}-old`); mkdirSync(f.dir); }
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    const calls: string[] = [];
    const cfg = parseGitHubSourceConfig(githubConfig, invalid === 'source-root' ? alternate : f.dir);
    try {
      await expect(runGitHubSync(engine, f.id, cfg, options, githubFetch({ calls }))).rejects.toBeInstanceOf(Error);
      expect(calls).toHaveLength(0);
      expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.id])).toHaveLength(0);
    } finally {
      await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
      if (invalid === 'source-root') await engine.executeRaw('UPDATE sources SET local_path=$2 WHERE id=$1', [f.id, f.dir]);
      else if (invalid === 'foreign-owner') await engine.executeRaw('UPDATE persistence_worktrees SET owner_host_id=$2::uuid WHERE id=$1::uuid', [f.binding.worktree_id, f.binding.owner_host_id]);
      else if (invalid === 'lock-file') { rmSync(f.binding.coordination_path!, { recursive: true }); renameSync(`${f.binding.coordination_path}-old`, f.binding.coordination_path!); }
      else { rmSync(f.dir, { recursive: true }); renameSync(`${f.dir}-old`, f.dir); }
      await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    }
  }
}), 120_000);

test('previously materialized connector pages stay canonical-file backed with managed writer enforcement', async () => withEnv(env, async () => {
  for (const engine of engines) for (const connector of ['google', 'github'] as const) {
    const config = connector === 'google' ? googleConfig : githubConfig;
    const f = await source(engine, config);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    let body = 'Legacy organization';
    const fetcher = async (url: string) => {
      if (connector === 'github') return new URL(url).pathname.endsWith('/issues/1') ? json({ ...issueFixture, body }) : githubFetch()(url);
      if (url.includes('/settings/sendAs')) return json({ sendAs: [] });
      return json({ connections: [{ ...contact('first', 'First Example'), organizations: [{ name: body }] }], nextSyncToken: 'contacts-legacy' });
    };
    const run = () => connector === 'google'
      ? runGoogleSync(engine, f.id, parseGoogleSourceConfig(config, f.dir), options, withGoogleAccount(fetcher))
      : runGitHubSync(engine, f.id, parseGitHubSourceConfig(config, f.dir), { ...options, githubItem: { repo: 'acme-example/app', number: 1, kind: 'issue' } }, fetcher);
    await run();
    const slug = connector === 'google' ? 'people/first-example' : 'gh/acme-example/app/1';
    const path = join(f.dir, `${slug}.md`);
    expect(readFileSync(path, 'utf8')).toContain('Legacy organization');
    await claimWorktree(engine, f.id, f.dir);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    body = 'Managed organization';
    expect((await run()).modified).toBe(1);
    expect(readFileSync(path, 'utf8')).toContain('Managed organization');
    const page = await engine.getPage(slug, { sourceId: f.id });
    expect(page).not.toBeNull();
    expect(parseMarkdown(readFileSync(path, 'utf8'), slug).compiled_truth).toBe(page!.compiled_truth);
    expect(page?.source_path).toBe(`${slug}.md`);
  }
}), 120_000);

test('a file edit after bound connector admission survives resident replay and prevents checkpoint advancement', async () => withEnv(env, async () => {
  for (const engine of engines) {
    const f = await boundSource(engine, githubConfig);
    let body = 'Original bound body';
    const fetcher = async (url: string) => new URL(url).pathname.endsWith('/issues/1') ? json({ ...issueFixture, body }) : githubFetch()(url);
    const run = () => runGitHubSync(engine, f.id, parseGitHubSourceConfig(githubConfig, f.dir), { ...options, githubItem: { repo: 'acme-example/app', number: 1, kind: 'issue' } }, fetcher);
    await run();
    await disposePersistenceConsumer(engine);
    const checkpoint = await sourceCheckpoint(engine, f.id);
    await engine.executeRaw("UPDATE persistence_worktrees SET state='draining' WHERE id=$1::uuid", [f.binding.worktree_id]);
    body = 'New API body';
    expect(await withPausedOwnerBudget(() => run())).toMatchObject({ status: 'partial', reason: 'writer_pending' });
    const [accepted] = await engine.executeRaw<WriteRequest>("SELECT * FROM persistence_requests WHERE source_id=$1 AND state='queued' ORDER BY sequence LIMIT 1", [f.id]);
    await disposePersistenceConsumer(engine);
    const path = join(f.dir, 'gh/acme-example/app/1.md');
    const edited = readFileSync(path, 'utf8') + '\n';
    writeFileSync(path, edited);
    await engine.executeRaw("UPDATE persistence_worktrees SET state='active' WHERE id=$1::uuid", [f.binding.worktree_id]);
    const done = await waitForWrite(engine, accepted, { engine: engine.kind });
    expect(done).toMatchObject({ state: 'conflict', error_code: 'source_changed' });
    expect(readFileSync(path, 'utf8')).toBe(edited);
    expect((await engine.getPage('gh/acme-example/app/1', { sourceId: f.id }))?.compiled_truth).toContain('Original bound body');
    expect(await sourceCheckpoint(engine, f.id)).toEqual(checkpoint);
  }
}), 120_000);

test('competing Google sweeps CAS their checkpoints instead of skipping each other', async () => withEnv(env, async () => {
  for (const engine of engines) {
    const f = await source(engine, googleConfig);
    const cfg = parseGoogleSourceConfig(googleConfig, f.dir);
    let arrived = 0;
    let release!: () => void;
    let entered!: () => void;
    const firstFetch = new Promise<void>(resolve => { entered = resolve; });
    const both = new Promise<void>(resolve => { release = resolve; });
    const run = (token: string) => runGoogleSync(engine, f.id, cfg, options, withGoogleAccount(async url => {
      if (url.includes('/settings/sendAs')) return json({ sendAs: [] });
      arrived++;
      entered();
      await both;
      return json({ connections: [contact(token, `${token} Example`)], nextSyncToken: token });
    }));
    const first = run('first');
    await firstFetch;
    const second = run('second');
    const settled = second.finally(release);
    settled.catch(() => {});
    const timer = setTimeout(release, 1000);
    const results = await Promise.allSettled([first, settled]).finally(() => clearTimeout(timer));
    expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(1);
    const rejected = results.find(result => result.status === 'rejected') as PromiseRejectedResult;
    expect(rejected.reason).toMatchObject({ name: 'LockUnavailableError' });
    expect(arrived).toBe(1);
    expect(await engine.executeRaw('SELECT slug FROM pages WHERE source_id=$1 AND deleted_at IS NULL', [f.id])).toHaveLength(1);
  }
}), 120_000);

test('resident publication revalidates accepted connector revisions, incarnations, roots, and writer grants', async () => withEnv(env, async () => {
  for (const engine of engines) for (const change of ['page', 'source', 'root', 'grant'] as const) {
    const f = await source(engine, githubConfig);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    const binding = await claimWorktree(engine, f.id, f.dir);
    await engine.executeRaw("UPDATE persistence_worktrees SET state='draining' WHERE id=$1::uuid", [binding.worktree_id]);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    expect(await withPausedOwnerBudget(() => runGitHubSync(engine, f.id, parseGitHubSourceConfig(githubConfig, f.dir), options, githubFetch()))).toMatchObject({ status: 'partial', reason: 'writer_pending' });
    const [accepted] = await engine.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE source_id=$1', [f.id]);
    await disposePersistenceConsumer(engine);
    const [writer] = await engine.executeRaw<{ grant_ceiling: unknown }>('SELECT grant_ceiling FROM persistence_local_writers WHERE id=$1::uuid', [accepted.principal_id]);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    if (change === 'page') {
      await importFromContent(engine, 'gh/acme-example/app/1', '---\ntitle: Newer private fixture\nvisibility: private\n---\nNewer local content must survive.\n', { sourceId: f.id, sourcePath: 'gh/acme-example/app/1.md', noEmbed: true });
    } else if (change === 'source') {
      await engine.executeRaw('DELETE FROM sources WHERE id=$1', [f.id]);
      await engine.executeRaw('INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,$3::text::jsonb)', [f.id, f.dir, JSON.stringify(githubConfig)]);
    } else if (change === 'root') {
      const alternate = join(home, `changed-root-${randomUUID()}`);
      mkdirSync(alternate);
      await engine.executeRaw('UPDATE sources SET local_path=$2 WHERE id=$1', [f.id, alternate]);
    } else {
      await engine.executeRaw("UPDATE persistence_local_writers SET grant_ceiling=jsonb_set(grant_ceiling,'{scopes}','[]'::jsonb) WHERE id=$1::uuid", [accepted.principal_id]);
    }
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    await engine.executeRaw("UPDATE persistence_worktrees SET state='active' WHERE id=$1::uuid", [binding.worktree_id]);
    try {
      const done = await waitForWrite(engine, accepted, { engine: engine.kind });
      expect(done.state).toBe(change === 'grant' ? 'failed' : 'conflict');
      expect(done.error_code).toBe(change === 'grant' ? 'permission_denied' : change === 'page' ? 'revision_conflict' : 'source_changed');
      expect(await sourceCheckpoint(engine, f.id)).toHaveLength(0);
      const page = await engine.getPage('gh/acme-example/app/1', { sourceId: f.id });
      if (change === 'page') {
        expect(page?.compiled_truth).toContain('Newer local content');
        expect(page?.frontmatter.visibility).toBe('private');
      } else expect(page).toBeNull();
    } finally {
      await engine.executeRaw('UPDATE persistence_local_writers SET grant_ceiling=$2::text::jsonb WHERE id=$1::uuid', [accepted.principal_id, JSON.stringify(writer.grant_ceiling)]);
    }
  }
}), 120_000);

test('aged live connector cursors survive actual checkpoint purge and normal incremental resume', async () => withEnv(env, async () => {
  for (const engine of engines) for (const connector of ['google', 'github'] as const) {
    const config = connector === 'google' ? googleConfig : githubConfig;
    const f = await source(engine, config);
    const calls: string[] = [];
    const fetcher = async (url: string) => {
      calls.push(url);
      if (connector === 'github') return githubFetch()(url);
      if (url.includes('/settings/sendAs')) return json({ sendAs: [] });
      return json({ connections: [contact('first', 'First Example')], nextSyncToken: 'retained-contacts-cursor' });
    };
    const run = () => connector === 'google'
      ? runGoogleSync(engine, f.id, parseGoogleSourceConfig(config, f.dir), options, withGoogleAccount(fetcher))
      : runGitHubSync(engine, f.id, parseGitHubSourceConfig(config, f.dir), options, fetcher);
    await run();
    await disposePersistenceConsumer(engine);
    const checkpoint = await sourceCheckpoint(engine, f.id);
    expect(checkpoint).toHaveLength(1);
    await engine.executeRaw("UPDATE op_checkpoints SET updated_at=now()-interval '8 days' WHERE op='managed-connector'");
    const stale = randomUUID();
    await engine.executeRaw("INSERT INTO op_checkpoints(op,fingerprint,completed_keys,updated_at) VALUES('embed',$1,'[]'::jsonb,now()-interval '8 days')", [stale]);
    expect(await purgeStaleCheckpoints(engine)).toBeGreaterThanOrEqual(1);
    expect(await engine.executeRaw("SELECT 1 FROM op_checkpoints WHERE op='embed' AND fingerprint=$1", [stale])).toHaveLength(0);
    expect(await sourceCheckpoint(engine, f.id)).toEqual(checkpoint);
    calls.length = 0;
    expect((await run()).status).not.toBe('partial');
    expect(calls.some(url => connector === 'google' ? url.includes('syncToken=retained-contacts-cursor')
      : new URL(url).pathname.endsWith('/issues') && new URL(url).searchParams.has('since'))).toBe(true);
  }
}), 120_000);

test('a fact withdrawn between bound connector preparation and publication leaves the canonical file and page unchanged', async () => withEnv(env, async () => {
  for (const engine of engines) {
    const f = await boundSource(engine, githubConfig);
    const claim = 'withdrawn between connector preparation and publication';
    let body = 'Original bound body';
    const fetcher = async (url: string) => new URL(url).pathname.endsWith('/issues/1') ? json({ ...issueFixture, body }) : githubFetch()(url);
    const run = () => runGitHubSync(engine, f.id, parseGitHubSourceConfig(githubConfig, f.dir), { ...options, githubItem: { repo: 'acme-example/app', number: 1, kind: 'issue' } }, fetcher);
    await run();
    await disposePersistenceConsumer(engine);
    const slug = 'gh/acme-example/app/1', path = join(f.dir, `${slug}.md`);
    // GBRA-221: a provider body can no longer bring a live fence (renders neutralize it), so the claim reaches the
    // prepared import the way brain-added facts do: a stored fence the connector carries into the re-render.
    expect(await writeSingleFact(engine, f.id, { fact: claim, kind: 'fact', entity: slug, visibility: 'world', provenance: 'test evidence', remote: false }))
      .toMatchObject({ status: 'inserted' });
    await disposePersistenceConsumer(engine);
    expect(readFileSync(path, 'utf8')).toContain(claim);
    const original = readFileSync(path, 'utf8');
    await engine.executeRaw("UPDATE persistence_worktrees SET state='draining' WHERE id=$1::uuid", [f.binding.worktree_id]);
    body = 'Updated bound body';
    expect(await withPausedOwnerBudget(() => run())).toMatchObject({ status: 'partial', reason: 'writer_pending' });
    await disposePersistenceConsumer(engine);
    await engine.executeRaw("UPDATE persistence_worktrees SET state='active' WHERE id=$1::uuid", [f.binding.worktree_id]);
    const claimed = (await claimNextWrite(engine, localHostId()))!;
    expect(claimed.intent?.kind).toBe('connector_v2_import');
    const prepared = await prepareConnectorMutation(engine, claimed);
    expect(prepared.file?.content).toContain(claim);
    const fact = await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], () =>
      tx.insertFact({ fact: claim, source: 'remember', visibility: 'world' }, { source_id: f.id }), TEST_WRITE_ATTRIBUTION));
    await engine.transaction(tx => withCoordinatedWrite(tx, [f.id], () => recordFactWithdrawal(tx, fact.id, f.id, true), TEST_WRITE_ATTRIBUTION));
    const boundaries: string[] = [];
    const before = (await engine.readPageSnapshot(slug, { sourceId: f.id }))!;
    const outcome = await publishMutation(engine, claimed, prepared, localHostId(), {
      boundary: async name => { boundaries.push(name); }, fileBoundary: name => { boundaries.push(name); } });
    expect(outcome).toMatchObject({ state: 'conflict', error_code: 'revision_conflict' });
    expect(boundaries).not.toContain('before_publication');
    expect(boundaries).not.toContain('before_file');
    expect(readFileSync(path, 'utf8')).toBe(original);
    expect((await engine.readPageSnapshot(slug, { sourceId: f.id }))?.revision).toBe(before.revision);
  }
}), 120_000);