Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
40.1 KB
Raw Blame
/**
 * v0.26.5 — destructive-guard unit tests.
 *
 * Source-level guard against accidental data loss. Three layers:
 *  1. Impact assessment (counts pages/chunks/embeddings/files for a source)
 *  2. Confirmation gate (`--confirm-destructive` required when data exists;
 *     `--yes` alone rejected)
 *  3. Soft-delete with 72h TTL (column-based as of v0.26.5; JSONB shape was
 *     migrated in v33)
 *
 * Run against PGLite — the contract logic is identical on Postgres but
 * PGLite is fast + DATABASE_URL-free. Postgres-specific paths (CONCURRENTLY,
 * RLS) are covered separately by E2E tests.
 */

import { describe, test, expect, beforeAll, afterAll, spyOn } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { gbrainPath } from '../src/core/config.ts';
import {
  assessDestructiveImpact,
  checkDestructiveConfirmation,
  softDeleteSource,
  restoreSource,
  listArchivedSources,
  purgeExpiredSources,
  formatImpact,
  formatSoftDelete,
  clientsReferencingSource,
  formatClientReferentsBlock,
  SOFT_DELETE_TTL_HOURS,
  type DestructiveImpact,
} from '../src/core/destructive-guard.ts';

// Tier 3 opt-out — these tests need the cold-init schema path so the v33
// migration columns exist on the brain under test. Unset for this file's
// tests and restore afterwards: a CI shard runs hundreds of files in ONE bun
// process (scripts/test-shard.sh), so a module-scope delete would cold-boot
// every later engine in the shard (check:test-env-opt-ins pins this shape).
let savedSnapshot: string | undefined;
beforeAll(() => {
  savedSnapshot = process.env.GBRAIN_PGLITE_SNAPSHOT;
  delete process.env.GBRAIN_PGLITE_SNAPSHOT;
});
afterAll(() => {
  if (savedSnapshot === undefined) delete process.env.GBRAIN_PGLITE_SNAPSHOT;
  else process.env.GBRAIN_PGLITE_SNAPSHOT = savedSnapshot;
});

async function setupBrain(): Promise<PGLiteEngine> {
  const engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
  return engine;
}

async function seedSource(engine: PGLiteEngine, id: string, opts?: { withPages?: number }): Promise<void> {
  await engine.executeRaw(
    `INSERT INTO sources (id, name) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING`,
    [id, id],
  );
  const count = opts?.withPages ?? 0;
  for (let i = 0; i < count; i++) {
    await engine.executeRaw(
      `INSERT INTO pages (source_id, slug, type, title) VALUES ($1, $2, 'note', $3)`,
      [id, `${id}/page-${i}`, `Page ${i}`],
    );
  }
}

async function setRawSourceConfig(engine: PGLiteEngine, id: string, rawJson: string): Promise<void> {
  await engine.executeRaw(
    `UPDATE sources SET config = $2::text::jsonb WHERE id = $1`,
    [id, rawJson],
  );
}

async function readSourceConfig(engine: PGLiteEngine, id: string): Promise<Record<string, unknown>> {
  const rows = await engine.executeRaw<{ config: unknown }>(
    `SELECT config FROM sources WHERE id = $1`,
    [id],
  );
  const config = rows[0].config;
  return typeof config === 'string' ? JSON.parse(config) : config as Record<string, unknown>;
}

describe('assessDestructiveImpact', () => {
  let engine: PGLiteEngine;

  beforeAll(async () => {
    engine = await setupBrain();
  }, 30000);

  afterAll(async () => {
    await engine.disconnect();
  });

  test('returns null for a non-existent source', async () => {
    const impact = await assessDestructiveImpact(engine, 'aim-does-not-exist');
    expect(impact).toBeNull();
  });

  test('counts zero across the board for an empty source', async () => {
    await seedSource(engine, 'aim-empty', { withPages: 0 });
    const impact = await assessDestructiveImpact(engine, 'aim-empty');
    expect(impact).not.toBeNull();
    expect(impact!.pageCount).toBe(0);
    expect(impact!.chunkCount).toBe(0);
    expect(impact!.embeddingCount).toBe(0);
    expect(impact!.fileCount).toBe(0);
    // Empty-source summary is the safe message, not the "permanently delete" warning.
    expect(impact!.summary).toContain('safe to remove');
  });

  test('counts pages correctly for a populated source', async () => {
    await seedSource(engine, 'aim-populated', { withPages: 3 });
    const impact = await assessDestructiveImpact(engine, 'aim-populated');
    expect(impact!.pageCount).toBe(3);
    expect(impact!.summary).toContain('3 pages');
    expect(impact!.summary).toContain('permanently delete');
  });

  test('source-scopes pages — multi-source isolation', async () => {
    await seedSource(engine, 'aim-src-a', { withPages: 2 });
    await seedSource(engine, 'aim-src-b', { withPages: 5 });
    const a = await assessDestructiveImpact(engine, 'aim-src-a');
    const b = await assessDestructiveImpact(engine, 'aim-src-b');
    expect(a!.pageCount).toBe(2);
    expect(b!.pageCount).toBe(5);
  });

  test('counts facts — a zero-page fact-holding source is data at risk, not "safe to remove"', async () => {
    // Revoked-agent-workspace shape: zero pages, facts present (the primary
    // agent write lane). Pre-fix the preview said "safe to remove" while the
    // delete would cascade the facts away.
    await seedSource(engine, 'aim-facts-only', { withPages: 0 });
    await engine.executeRaw(
      `INSERT INTO facts (source_id, fact, source) VALUES ($1, 'agent memory row', 'test'), ($1, 'second memory row', 'test')`,
      ['aim-facts-only'],
    );
    const impact = await assessDestructiveImpact(engine, 'aim-facts-only');
    expect(impact!.pageCount).toBe(0);
    expect(impact!.factCount).toBe(2);
    expect(impact!.summary).toContain('2 facts');
    expect(impact!.summary).toContain('permanently delete');
    expect(impact!.summary).not.toContain('safe to remove');
  });
});

describe('checkDestructiveConfirmation (gate truth table)', () => {
  const populated: DestructiveImpact = {
    sourceId: 'has-data',
    sourceName: 'has-data',
    pageCount: 100,
    chunkCount: 500,
    embeddingCount: 500,
    fileCount: 0,
    summary: '⚠️  This will permanently delete: 100 pages, 500 chunks, 500 embeddings',
  };

  const empty: DestructiveImpact = {
    sourceId: 'no-data',
    sourceName: 'no-data',
    pageCount: 0,
    chunkCount: 0,
    embeddingCount: 0,
    fileCount: 0,
    summary: 'Source "no-data" has no data (safe to remove).',
  };

  test('dry-run always passes regardless of flags', () => {
    expect(checkDestructiveConfirmation(populated, { dryRun: true })).toBeNull();
    expect(checkDestructiveConfirmation(populated, { yes: true, dryRun: true })).toBeNull();
  });

  test('empty source passes without --confirm-destructive', () => {
    expect(checkDestructiveConfirmation(empty, {})).toBeNull();
    expect(checkDestructiveConfirmation(empty, { yes: true })).toBeNull();
  });

  test('--confirm-destructive passes regardless of --yes', () => {
    expect(checkDestructiveConfirmation(populated, { confirmDestructive: true })).toBeNull();
    expect(checkDestructiveConfirmation(populated, { yes: true, confirmDestructive: true })).toBeNull();
  });

  test('--yes alone with data is REJECTED with guidance message', () => {
    const msg = checkDestructiveConfirmation(populated, { yes: true });
    expect(msg).not.toBeNull();
    expect(msg).toContain('--confirm-destructive');
    expect(msg).toContain('archive');
  });

  test('no flags + populated source rejects', () => {
    const msg = checkDestructiveConfirmation(populated, {});
    expect(msg).not.toBeNull();
    expect(msg).toContain('--confirm-destructive');
  });

  test('a fact-only source requires --confirm-destructive (facts gate exactly like pages)', () => {
    const factOnly: DestructiveImpact = {
      sourceId: 'revoked-agent-workspace',
      sourceName: 'revoked-agent-workspace',
      pageCount: 0,
      chunkCount: 0,
      embeddingCount: 0,
      fileCount: 0,
      factCount: 7,
      summary: '⚠️  This will permanently delete: 7 facts',
    };
    // No flags → blocked; --yes alone → still blocked (mirrors pages).
    expect(checkDestructiveConfirmation(factOnly, {})).toContain('--confirm-destructive');
    expect(checkDestructiveConfirmation(factOnly, { yes: true })).toContain('--confirm-destructive');
    // --confirm-destructive and --dry-run pass.
    expect(checkDestructiveConfirmation(factOnly, { confirmDestructive: true })).toBeNull();
    expect(checkDestructiveConfirmation(factOnly, { dryRun: true })).toBeNull();
    // Hand-built literal WITHOUT factCount stays valid (optional field, ?? 0).
    expect(checkDestructiveConfirmation({ ...factOnly, factCount: undefined }, { yes: true })).toBeNull();
  });
});

describe('soft-delete + restore lifecycle (column-based v0.26.5)', () => {
  // ONE engine for the whole describe — cold init runs ~29 migrations, ~3s.
  // Each test uses a unique source id so they don't cross-pollute.
  let engine: PGLiteEngine;

  beforeAll(async () => {
    engine = await setupBrain();
  }, 30000);

  afterAll(async () => {
    await engine.disconnect();
  });

  test('softDeleteSource flips column shape + sets TTL', async () => {
    const id = 'sd-flips';
    await seedSource(engine, id, { withPages: 2 });
    const before = Date.now();
    const result = await softDeleteSource(engine, id);
    const after = Date.now();
    expect(result).not.toBeNull();
    expect(result!.id).toBe(id);
    expect(result!.pageCount).toBe(2);
    const ttlMs = SOFT_DELETE_TTL_HOURS * 60 * 60 * 1000;
    expect(result!.expiresAt.getTime()).toBeGreaterThanOrEqual(before + ttlMs - 1000);
    expect(result!.expiresAt.getTime()).toBeLessThanOrEqual(after + ttlMs + 1000);
    const rows = await engine.executeRaw<{ archived: boolean; archived_at: string }>(
      `SELECT archived, archived_at FROM sources WHERE id = $1`,
      [id],
    );
    expect(rows[0].archived).toBe(true);
    expect(rows[0].archived_at).not.toBeNull();
  });

  test('softDeleteSource is idempotent-as-null on already-archived', async () => {
    const id = 'sd-idem';
    await seedSource(engine, id, { withPages: 1 });
    await softDeleteSource(engine, id);
    expect(await softDeleteSource(engine, id)).toBeNull();
  });

  test('softDeleteSource returns null for unknown source', async () => {
    expect(await softDeleteSource(engine, 'sd-unknown-xyz')).toBeNull();
  });

  test('softDeleteSource flips federated:false in JSONB but archived state is column-based', async () => {
    const id = 'sd-jsonb';
    await seedSource(engine, id, { withPages: 1 });
    await softDeleteSource(engine, id);
    const rows = await engine.executeRaw<{ config: any; archived: boolean }>(
      `SELECT config, archived FROM sources WHERE id = $1`,
      [id],
    );
    const config = typeof rows[0].config === 'string' ? JSON.parse(rows[0].config) : rows[0].config;
    expect(config.federated).toBe(false);
    expect(rows[0].archived).toBe(true);
    // Issue 5 contract: archived must NOT live in config any more.
    expect(config.archived).toBeUndefined();
    expect(config.archived_at).toBeUndefined();
  });

  test('softDeleteSource normalizes nested-string config without dropping keys', async () => {
    const id = 'sd-string-config';
    await seedSource(engine, id);
    await setRawSourceConfig(
      engine,
      id,
      JSON.stringify(JSON.stringify({ federated: true, remote_url: 'https://example.invalid/repo' })),
    );
    await softDeleteSource(engine, id);
    expect(await readSourceConfig(engine, id)).toEqual({
      federated: false,
      remote_url: 'https://example.invalid/repo',
    });
  });

  test('softDeleteSource flattens recoverable array config without dropping keys', async () => {
    const id = 'sd-array-config';
    await seedSource(engine, id);
    await setRawSourceConfig(engine, id, JSON.stringify([
      '{"remote_url":"https://example.invalid/repo"}',
      { tracked_branch: 'main' },
      { federated: true },
      'not-json',
    ]));
    await softDeleteSource(engine, id);
    expect(await readSourceConfig(engine, id)).toEqual({
      federated: false,
      remote_url: 'https://example.invalid/repo',
      tracked_branch: 'main',
    });
  });

  test('restoreSource clears the column state and re-federates by default', async () => {
    const id = 'sd-restore-fed';
    await seedSource(engine, id, { withPages: 1 });
    await softDeleteSource(engine, id);
    expect(await restoreSource(engine, id)).toBe(true);
    const rows = await engine.executeRaw<{ archived: boolean; archived_at: string | null; config: any }>(
      `SELECT archived, archived_at, config FROM sources WHERE id = $1`,
      [id],
    );
    expect(rows[0].archived).toBe(false);
    expect(rows[0].archived_at).toBeNull();
    const config = typeof rows[0].config === 'string' ? JSON.parse(rows[0].config) : rows[0].config;
    expect(config.federated).toBe(true);
  });

  test('restoreSource respects --no-federate (refederate=false)', async () => {
    const id = 'sd-no-fed';
    await seedSource(engine, id, { withPages: 1 });
    await softDeleteSource(engine, id);
    await restoreSource(engine, id, false);
    const rows = await engine.executeRaw<{ config: any }>(
      `SELECT config FROM sources WHERE id = $1`,
      [id],
    );
    const config = typeof rows[0].config === 'string' ? JSON.parse(rows[0].config) : rows[0].config;
    expect(config.federated).toBe(false);
  });

  test('restoreSource repairs array config and preserves recoverable keys', async () => {
    const id = 'sd-restore-array';
    await seedSource(engine, id);
    await engine.executeRaw(
      `UPDATE sources
          SET archived = true,
              archived_at = now(),
              archive_expires_at = now() + interval '1 hour'
        WHERE id = $1`,
      [id],
    );
    await setRawSourceConfig(engine, id, JSON.stringify([
      { remote_url: 'https://example.invalid/repo' },
      '{"federated":false,"tracked_branch":"main"}',
    ]));
    expect(await restoreSource(engine, id)).toBe(true);
    expect(await readSourceConfig(engine, id)).toEqual({
      federated: true,
      remote_url: 'https://example.invalid/repo',
      tracked_branch: 'main',
    });
  });

  test('restoreSource is idempotent-as-false on already-active', async () => {
    const id = 'sd-active';
    await seedSource(engine, id);
    expect(await restoreSource(engine, id)).toBe(false);
  });

  test('listArchivedSources filters via the archived column, not JSONB', async () => {
    const archivedId = 'la-archived';
    const liveId = 'la-live';
    await seedSource(engine, archivedId, { withPages: 3 });
    await seedSource(engine, liveId, { withPages: 1 });
    await softDeleteSource(engine, archivedId);
    const archived = await listArchivedSources(engine);
    const ids = archived.map((a) => a.id);
    expect(ids).toContain(archivedId);
    expect(ids).not.toContain(liveId);
    const archivedRow = archived.find((a) => a.id === archivedId)!;
    expect(archivedRow.pageCount).toBe(3);
  });

  test('purgeExpiredSources only deletes rows with archive_expires_at <= now()', async () => {
    const expiredId = 'pe-expired';
    const recoverableId = 'pe-recoverable';
    await seedSource(engine, expiredId, { withPages: 2 });
    await seedSource(engine, recoverableId, { withPages: 1 });
    await softDeleteSource(engine, expiredId);
    await softDeleteSource(engine, recoverableId);
    await engine.executeRaw(
      `UPDATE sources SET archive_expires_at = now() - INTERVAL '1 hour' WHERE id = $1`,
      [expiredId],
    );
    const { purged, blocked } = await purgeExpiredSources(engine);
    expect(purged).toContain(expiredId);
    expect(purged).not.toContain(recoverableId);
    expect(blocked).toEqual([]);
    const remainingPages = await engine.executeRaw<{ n: number }>(
      `SELECT COUNT(*)::int AS n FROM pages WHERE source_id = $1`,
      [expiredId],
    );
    expect(remainingPages[0].n).toBe(0);
  });

  test('gbrain#5452 — epoch or missing archive timestamps are never purge-eligible and are reported', async () => {
    const epochId = 'pe-epoch';
    const nullId = 'pe-null-expiry';
    await seedSource(engine, epochId, { withPages: 1 });
    await seedSource(engine, nullId, { withPages: 1 });
    await softDeleteSource(engine, epochId);
    await softDeleteSource(engine, nullId);
    await engine.executeRaw(
      `UPDATE sources SET archived_at = '1970-01-01T00:00:00Z', archive_expires_at = '1970-01-01T00:00:00Z' WHERE id = $1`,
      [epochId],
    );
    await engine.executeRaw(
      `UPDATE sources SET archive_expires_at = NULL WHERE id = $1`,
      [nullId],
    );
    const { purged, blocked } = await purgeExpiredSources(engine);
    expect(purged).not.toContain(epochId);
    expect(purged).not.toContain(nullId);
    expect(blocked.map((b) => b.id)).toEqual(expect.arrayContaining([epochId, nullId]));
    // Both sources and their pages survive — full contents intact.
    const intact = await engine.executeRaw<{ n: number }>(
      `SELECT COUNT(*)::int AS n FROM pages WHERE source_id IN ($1, $2)`,
      [epochId, nullId],
    );
    expect(intact[0].n).toBe(2);
    // Cleanup: leftover archived rows are reported as suspects by every
    // later purge sweep in this describe.
    await engine.executeRaw(`DELETE FROM sources WHERE id IN ($1, $2)`, [epochId, nullId]);
  });

  test('gbrain#5452 — a missing/epoch archived_at refuses purge even with a normal past expiry', async () => {
    const epochArchId = 'pe-epoch-arch';
    const nullArchId = 'pe-null-arch';
    await seedSource(engine, epochArchId, { withPages: 1 });
    await seedSource(engine, nullArchId, { withPages: 1 });
    await softDeleteSource(engine, epochArchId);
    await softDeleteSource(engine, nullArchId);
    // Past expiry is a perfectly normal value here — the refusal comes from
    // archived_at, which can no longer prove the 72h window ever existed.
    await engine.executeRaw(
      `UPDATE sources SET archived_at = '1970-01-01T00:00:00Z', archive_expires_at = now() - INTERVAL '1 hour' WHERE id = $1`,
      [epochArchId],
    );
    await engine.executeRaw(
      `UPDATE sources SET archived_at = NULL, archive_expires_at = now() - INTERVAL '1 hour' WHERE id = $1`,
      [nullArchId],
    );
    const { purged, blocked } = await purgeExpiredSources(engine);
    expect(purged).not.toContain(epochArchId);
    expect(purged).not.toContain(nullArchId);
    expect(blocked.map((b) => b.id)).toEqual(expect.arrayContaining([epochArchId, nullArchId]));
    const intact = await engine.executeRaw<{ n: number }>(
      `SELECT COUNT(*)::int AS n FROM pages WHERE source_id IN ($1, $2)`,
      [epochArchId, nullArchId],
    );
    expect(intact[0].n).toBe(2);
    await engine.executeRaw(`DELETE FROM sources WHERE id IN ($1, $2)`, [epochArchId, nullArchId]);
  });

  test('gbrain#5452 — timestamps flipped to epoch/missing after candidate selection are refused at delete time', async () => {
    const flipExpiryId = 'pe-flip-expiry';
    const flipArchId = 'pe-flip-arch';
    await seedSource(engine, flipExpiryId, { withPages: 1 });
    await seedSource(engine, flipArchId, { withPages: 1 });
    await softDeleteSource(engine, flipExpiryId);
    await softDeleteSource(engine, flipArchId);
    // Both start as legitimate candidates: real archived_at, past expiry.
    await engine.executeRaw(
      `UPDATE sources SET archive_expires_at = now() - INTERVAL '1 hour' WHERE id IN ($1, $2)`,
      [flipExpiryId, flipArchId],
    );
    // The sweep reads candidates, then deletes one row at a time. Reproduce a
    // stamp flip landing in between: the moment the first DELETE arrives, both
    // rows' stamps degrade to the refusal set — the DELETE itself must refuse.
    const orig = engine.executeRaw.bind(engine);
    let flipped = false;
    engine.executeRaw = (async (sql: string, params?: unknown[]) => {
      if (!flipped && typeof sql === 'string' && sql.includes('DELETE FROM sources')) {
        flipped = true;
        await orig(
          `UPDATE sources SET archive_expires_at = '1970-01-01T00:00:00Z' WHERE id = $1`,
          [flipExpiryId],
        );
        await orig(`UPDATE sources SET archived_at = NULL WHERE id = $1`, [flipArchId]);
      }
      return orig(sql, params);
    }) as typeof engine.executeRaw;
    let purged: string[] = [];
    try {
      ({ purged } = await purgeExpiredSources(engine));
    } finally {
      engine.executeRaw = orig;
    }
    expect(flipped).toBe(true);
    expect(purged).not.toContain(flipExpiryId);
    expect(purged).not.toContain(flipArchId);
    const intact = await engine.executeRaw<{ n: number }>(
      `SELECT COUNT(*)::int AS n FROM pages WHERE source_id IN ($1, $2)`,
      [flipExpiryId, flipArchId],
    );
    expect(intact[0].n).toBe(2);
    await engine.executeRaw(`DELETE FROM sources WHERE id IN ($1, $2)`, [flipExpiryId, flipArchId]);
  });

  test('gbrain#4115 — an FK-blocked source is reported and skipped; the deletable one still purges', async () => {
    const blockedId = 'pe-fk-blocked';
    const deletableId = 'pe-fk-deletable';
    await seedSource(engine, blockedId, { withPages: 1 });
    await seedSource(engine, deletableId, { withPages: 1 });
    await softDeleteSource(engine, blockedId);
    await softDeleteSource(engine, deletableId);
    await engine.executeRaw(
      `UPDATE sources SET archive_expires_at = now() - INTERVAL '1 hour' WHERE id IN ($1, $2)`,
      [blockedId, deletableId],
    );
    // A revoked-but-retained oauth client (soft-deleted via deleted_at) under
    // v64's ON DELETE RESTRICT — the exact production shape from the report.
    await engine.executeRaw(
      `INSERT INTO oauth_clients (client_id, client_name, source_id, deleted_at)
       VALUES ('cl-4115-test', 'test client', $1, now())`,
      [blockedId],
    );
    const { purged, blocked } = await purgeExpiredSources(engine);
    expect(purged).toContain(deletableId);
    expect(purged).not.toContain(blockedId);
    expect(blocked.map((b) => b.id)).toEqual([blockedId]);
    expect(blocked[0].reason).toContain('RESTRICT');
    // The blocked source is untouched (still archived, still expired) — the
    // next sweep retries it after the operator clears the client.
    const still = await engine.executeRaw<{ n: number }>(
      `SELECT COUNT(*)::int AS n FROM sources WHERE id = $1 AND archived = true`,
      [blockedId],
    );
    expect(still[0].n).toBe(1);
    // Cleanup so later tests are unaffected.
    await engine.executeRaw(`DELETE FROM oauth_clients WHERE client_id = 'cl-4115-test'`);
    await engine.executeRaw(`DELETE FROM sources WHERE id = $1`, [blockedId]);
  });

  test('purgeExpiredSources is no-op when nothing is past TTL', async () => {
    // After all earlier tests, there may still be archived rows whose
    // archive_expires_at is in the future. Force-update any leftover-past
    // rows OUT of expiration before this assertion (we only want to test
    // the no-op return here, not interfere with prior test state).
    await engine.executeRaw(
      `UPDATE sources SET archive_expires_at = now() + INTERVAL '72 hours' WHERE archived = true`,
    );
    const result = await purgeExpiredSources(engine);
    expect(result.purged).toEqual([]);
    expect(result.blocked).toEqual([]);
  });

  // GBRA-130 A-50: a non-FK error is never read as FK-blocked. One source's own failure (57014) is blocked with its
  // classified code and the manual purge, and the sweep continues; a run-scoped error (lost connection) still re-raises.
  const nonFkStub = (code: string, message: string) => ({
    async executeRaw(sql: string): Promise<Array<{ id: string }>> {
      if (sql.includes('archive_expires_at IS NULL')) return []; // #5452 unverified-archive listing: none here
      if (sql.includes('FROM persistence_brain')) return [{ enabled: false } as never]; // #6482: one well-formed unmanaged row
      if (sql.trimStart().startsWith('SELECT')) return [{ id: 'boom' }];
      throw Object.assign(new Error(message), { code }); // NOT the FK class
    },
  }) as never;

  test('gbrain#4115 — a NON-FK error re-raises instead of reading as blocked (review gap G8)', async () => {
    await expect(purgeExpiredSources(nonFkStub('08006', 'Connection terminated unexpectedly'))).rejects.toThrow('Connection terminated');
    const { purged, blocked } = await purgeExpiredSources(nonFkStub('57014', 'canceling statement due to statement timeout'));
    expect(purged).toEqual([]);
    expect(blocked.map(b => [b.id, b.code, b.fix?.next, b.fix?.command])).toEqual([['boom', 'statement_timeout', 'tell_user_to_run', 'gbrain sources purge boom --confirm-destructive']]);
    expect(blocked[0]!.reason).toContain('statement timeout');
    expect(blocked[0]!.reason).not.toContain('foreign key');
  });

  test('gbrain#4115 — a source restored between SELECT and DELETE is neither purged nor blocked (review gap G8)', async () => {
    const stub = {
      async executeRaw(sql: string): Promise<Array<{ id: string }>> {
        if (sql.includes('archive_expires_at IS NULL')) return []; // #5452 unverified-archive listing: none here
        if (sql.includes('FROM persistence_brain')) return [{ enabled: false } as never]; // #6482: one well-formed unmanaged row
        if (sql.trimStart().startsWith('SELECT')) return [{ id: 'restored-mid-sweep' }];
        return []; // per-id DELETE re-checks the expiry predicate → 0 rows
      },
    } as never;
    const { purged, blocked } = await purgeExpiredSources(stub);
    expect(purged).toEqual([]);
    expect(blocked).toEqual([]);
  });
});

// ── PR6 D5b: FK-RESTRICT lifecycle ──────────────────────────
// oauth_clients.source_id is ON DELETE RESTRICT; the guard must surface the
// block BEFORE a hard delete instead of letting the raw FK violation escape.

describe('FK-RESTRICT lifecycle (clientsReferencingSource + purge skip)', () => {
  // Own engine — the soft-delete describe's purge tests mutate every
  // archived row's expiry; don't cross-pollute.
  let engine: PGLiteEngine;

  beforeAll(async () => {
    engine = await setupBrain();
  }, 30000);

  afterAll(async () => {
    await engine.disconnect();
  });

  async function seedClient(
    clientId: string,
    sourceId: string | null,
    opts?: { deleted?: boolean },
  ): Promise<void> {
    await engine.executeRaw(
      `INSERT INTO oauth_clients (client_id, client_name, source_id, deleted_at)
       VALUES ($1, $2, $3, ${opts?.deleted ? 'now()' : 'NULL'})
       ON CONFLICT (client_id) DO NOTHING`,
      [clientId, `${clientId}-name`, sourceId],
    );
  }

  test('clientsReferencingSource returns ALL physical referents (soft-deleted tagged), scoped to the source', async () => {
    await seedSource(engine, 'fk-ref-a');
    await seedSource(engine, 'fk-ref-b');
    await seedClient('cl-live-1', 'fk-ref-a');
    await seedClient('cl-live-2', 'fk-ref-a');
    await seedClient('cl-dead', 'fk-ref-a', { deleted: true });
    await seedClient('cl-other-src', 'fk-ref-b');
    await seedClient('cl-no-src', null);

    // PHYSICAL semantics: the soft-deleted row still holds the FK, so it is
    // returned too — tagged deleted:true, never silently dropped.
    const refs = await clientsReferencingSource(engine, 'fk-ref-a');
    expect(refs).toEqual([
      { clientId: 'cl-dead', clientName: 'cl-dead-name', deleted: true },
      { clientId: 'cl-live-1', clientName: 'cl-live-1-name', deleted: false },
      { clientId: 'cl-live-2', clientName: 'cl-live-2-name', deleted: false },
    ]);
    expect(await clientsReferencingSource(engine, 'fk-ref-none')).toEqual([]);
  });

  test('a soft-deleted referent alone BLOCKS the remove/purge pre-check with the retained-row guidance', async () => {
    await seedSource(engine, 'fk-soft-only', { withPages: 1 });
    await seedClient('cl-soft-only', 'fk-soft-only', { deleted: true });

    // The pre-check truth (sources.ts blocks on referents.length > 0): the
    // helper must return the soft-deleted row, because the FK ignores
    // deleted_at and the hard delete WOULD fail at the database.
    const refs = await clientsReferencingSource(engine, 'fk-soft-only');
    expect(refs).toEqual([
      { clientId: 'cl-soft-only', clientName: 'cl-soft-only-name', deleted: true },
    ]);

    const block = formatClientReferentsBlock('fk-soft-only', refs);
    expect(block).toContain('Cannot delete source "fk-soft-only"');
    expect(block).toContain('Revoked-but-retained rows still block the FK');
    expect(block).toContain('hard-deletes them');
    expect(block).toContain('gbrain auth revoke-client "cl-soft-only"');
    // No live rows → no live-revoke section.
    expect(block).not.toContain('Revoke each live client first');
  });

  test('assessDestructiveImpact folds the referent count; formatImpact shows it', async () => {
    await seedSource(engine, 'fk-impact', { withPages: 1 });
    await seedClient('cl-impact', 'fk-impact');

    const impact = await assessDestructiveImpact(engine, 'fk-impact');
    expect(impact).not.toBeNull();
    expect(impact!.oauthClientCount).toBe(1);

    const out = formatImpact(impact!);
    expect(out).toContain('1 OAuth client(s) reference this source');
    expect(out).toContain('revoke-client');
  });

  test('assessDestructiveImpact reports zero referents for an unreferenced source', async () => {
    await seedSource(engine, 'fk-unref', { withPages: 1 });
    const impact = await assessDestructiveImpact(engine, 'fk-unref');
    expect(impact!.oauthClientCount).toBe(0);
    expect(formatImpact(impact!)).not.toContain('OAuth client');
  });

  test('purgeExpiredSources purges only the unreferenced expired source and reports the FK-held one as blocked', async () => {
    // Ported from #4238's string[]-contract version at merge: the sweep now
    // returns {purged, blocked} (chennai #4115 fix) — the skipped id and its
    // revoke guidance live in the structured result, not a stderr warn
    // (callers render it).
    await seedSource(engine, 'fk-purge-ref', { withPages: 1 });
    await seedSource(engine, 'fk-purge-free', { withPages: 1 });
    await seedClient('cl-purge-ref', 'fk-purge-ref');
    await softDeleteSource(engine, 'fk-purge-ref');
    await softDeleteSource(engine, 'fk-purge-free');
    await engine.executeRaw(
      `UPDATE sources SET archive_expires_at = now() - INTERVAL '1 hour' WHERE id = ANY($1::text[])`,
      [['fk-purge-ref', 'fk-purge-free']],
    );

    const { purged, blocked } = await purgeExpiredSources(engine);

    expect(purged).toEqual(['fk-purge-free']);
    expect(blocked.map((b) => b.id)).toEqual(['fk-purge-ref']);
    expect(blocked[0].reason).toContain('revoke-client');

    // Referenced source survives (blocked, not FK-crashed).
    const remaining = await engine.executeRaw<{ id: string }>(
      `SELECT id FROM sources WHERE id = ANY($1::text[])`,
      [['fk-purge-ref', 'fk-purge-free']],
    );
    expect(remaining.map((r) => r.id)).toEqual(['fk-purge-ref']);
  });

  test('purge block is PHYSICAL: a soft-deleted client row still blocks (FK ignores deleted_at)', async () => {
    await seedSource(engine, 'fk-purge-dead', { withPages: 1 });
    await seedClient('cl-purge-dead', 'fk-purge-dead', { deleted: true });
    await softDeleteSource(engine, 'fk-purge-dead');
    await engine.executeRaw(
      `UPDATE sources SET archive_expires_at = now() - INTERVAL '1 hour' WHERE id = $1`,
      ['fk-purge-dead'],
    );

    const { purged, blocked } = await purgeExpiredSources(engine);

    expect(purged).not.toContain('fk-purge-dead');
    expect(blocked.map((b) => b.id)).toContain('fk-purge-dead');
    const rows = await engine.executeRaw<{ id: string }>(
      `SELECT id FROM sources WHERE id = $1`, ['fk-purge-dead'],
    );
    expect(rows.length).toBe(1);
  });

  test('formatClientReferentsBlock lists clients + per-client revoke commands, split by liveness', () => {
    const block = formatClientReferentsBlock('acme-example', [
      { clientId: 'client-1', clientName: 'Agent One', deleted: false },
      { clientId: 'client-2', clientName: 'Agent Two', deleted: true },
    ]);
    expect(block).toContain('Cannot delete source "acme-example"');
    expect(block).toContain('2 OAuth client(s) reference this source');
    expect(block).toContain('Agent One (client-1)');
    expect(block).toContain('Agent Two (client-2)  [revoked, retained]');
    // Live rows get the hard-delete revoke guidance...
    expect(block).toContain('Revoke each live client first');
    expect(block).toContain('gbrain auth revoke-client "client-1"');
    // ...soft-deleted rows get the retained-rows-still-block guidance.
    expect(block).toContain('Revoked-but-retained rows still block the FK');
    expect(block).toContain('gbrain auth revoke-client "client-2"');
  });

  test('degrade ladder: missing oauth_clients table → [], missing deleted_at → all referents, other errors propagate', async () => {
    // Pre-oauth brain: no oauth_clients table at all → no referents by
    // construction (isUndefinedTableError arm).
    const noTable = {
      executeRaw: async () => {
        throw Object.assign(new Error('relation "oauth_clients" does not exist'), { code: '42P01' });
      },
    } as any;
    expect(await clientsReferencingSource(noTable, 'x')).toEqual([]);

    // Pre-migration brain: deleted_at column missing → falls back to ALL
    // referents (the 42703-retry idiom), tagged live (deleted:false — the
    // column that would say otherwise doesn't exist).
    const noColumn = {
      executeRaw: async (sql: string) => {
        if (sql.includes('deleted_at')) {
          throw Object.assign(new Error('column "deleted_at" does not exist'), { code: '42703' });
        }
        return [{ client_id: 'c1', client_name: 'n1' }];
      },
    } as any;
    expect(await clientsReferencingSource(noColumn, 'x')).toEqual([
      { clientId: 'c1', clientName: 'n1', deleted: false },
    ]);

    // Anything else (e.g. a dropped connection) must PROPAGATE — a swallowed
    // error here would let a hard delete proceed past live referents.
    const broken = {
      executeRaw: async () => { throw new Error('connection reset'); },
    } as any;
    await expect(clientsReferencingSource(broken, 'x')).rejects.toThrow('connection reset');
  });

  test('missing source_id column → [] (no column ⇒ no FK ⇒ no referents)', async () => {
    // Pre-v61 brain: oauth_clients exists but has no source_id column at all.
    const noSourceId = {
      executeRaw: async () => {
        throw Object.assign(new Error('column "source_id" does not exist'), { code: '42703' });
      },
    } as any;
    expect(await clientsReferencingSource(noSourceId, 'x')).toEqual([]);

    // Same brain shape must not break the purge path either. The per-source
    // sweep (chennai #4115) never queries oauth_clients at all — the FK, if
    // present, surfaces as SQLSTATE 23503 on the DELETE — so a pre-v61 brain
    // shape purges through the exact same code path.
    let sawOauthQuery = false;
    const purgeStub = {
      executeRaw: async (sql: string) => {
        if (sql.includes('oauth_clients')) sawOauthQuery = true;
        return sql.includes('FROM persistence_brain') ? [{ enabled: false }] : []; // #6482: one well-formed unmanaged row
      },
    } as any;
    expect(await purgeExpiredSources(purgeStub)).toEqual({ purged: [], blocked: [] });
    expect(sawOauthQuery).toBe(false);
  });
});

describe('formatters (display helpers)', () => {
  test('formatImpact renders the boxed preview with the source id and counts', () => {
    const impact: DestructiveImpact = {
      sourceId: 'media-corpus',
      sourceName: 'Media Corpus',
      pageCount: 5033,
      chunkCount: 22000,
      embeddingCount: 22000,
      fileCount: 0,
      summary: '⚠️  This will permanently delete: 5,033 pages, 22,000 chunks, 22,000 embeddings',
    };
    const out = formatImpact(impact);
    expect(out).toContain('Media Corpus');
    expect(out).toContain('media-corpus');
    expect(out).toContain('5,033');
    expect(out).toContain('22,000');
    expect(out).toContain('DESTRUCTIVE OPERATION');
    // cathedral-6: the box renders a Facts row (0 for a literal without it).
    expect(out).toMatch(/Facts:\s+0/);
  });

  test('formatImpact renders the facts count (mirrors the page-count line)', () => {
    const impact: DestructiveImpact = {
      sourceId: 'revoked-agent-workspace',
      sourceName: 'revoked-agent-workspace',
      pageCount: 0,
      chunkCount: 0,
      embeddingCount: 0,
      fileCount: 0,
      factCount: 1234,
      summary: '⚠️  This will permanently delete: 1,234 facts',
    };
    const out = formatImpact(impact);
    expect(out).toMatch(/Facts:\s+1,234/);
  });

  test('sources remove orders the row DELETE (in-tx) BEFORE external teardown (F1 structural pin)', () => {
    // A concurrent registration between the referents pre-check and the
    // DELETE must surface as the refusal, never as destroyed scaffolding
    // with the row still present — so the tx'd DELETE precedes unharden.
    const { readFileSync } = require('fs');
    const src = readFileSync(new URL('../src/commands/sources.ts', import.meta.url), 'utf-8');
    const removeStart = src.indexOf('async function runRemove');
    const removeEnd = src.indexOf('async function', removeStart + 1);
    const body = src.slice(removeStart, removeEnd);
    const deleteIdx = body.indexOf('deleteSourceRow(tx, id)');
    const teardownIdx = body.indexOf('unhardenBrainRepo');
    expect(deleteIdx).toBeGreaterThan(0);
    expect(teardownIdx).toBeGreaterThan(0);
    expect(deleteIdx).toBeLessThan(teardownIdx);
    // And the DELETE runs inside engine.transaction (atomic with the re-check).
    const txIdx = body.indexOf('engine.transaction');
    expect(txIdx).toBeGreaterThan(0);
    expect(txIdx).toBeLessThan(deleteIdx);
  });

  test('formatSoftDelete renders the post-archive guidance with restore command', () => {
    const out = formatSoftDelete({
      id: 'src-a',
      name: 'src-a',
      deletedAt: new Date(),
      expiresAt: new Date(Date.now() + 72 * 60 * 60 * 1000),
      pageCount: 100,
    });
    expect(out).toContain('archived');
    expect(out).toContain('restore src-a');
    expect(out).toContain('72');
  });
});

// ── Purge clone-cleanup containment ─────────────────────────
// gh_managed cleanup must never rm -rf the clone root itself (a corrupt row
// with local_path = the root would wipe every mirror), and only deletes the
// exact defaultCloneDir('<id>-github') shape the creation path pins.

describe('purgeExpiredSources — clone cleanup containment', () => {
  function purgeStubFor(id: string, localPath: string) {
    return {
      executeRaw: async (sql: string) => {
        if (sql.includes('FROM persistence_brain')) return [{ enabled: false }]; // #6482: one well-formed unmanaged row
        if (sql.trimStart().startsWith('SELECT')) {
          return [{ id, config: { kind: 'github', gh_managed: true }, local_path: localPath }];
        }
        return [{ id }];
      },
    } as never;
  }

  test('a corrupt row whose local_path IS the clone root never deletes sibling mirrors; the pinned shape still cleans up', async () => {
    const prevHome = process.env.GBRAIN_HOME;
    const homeParent = mkdtempSync(join(tmpdir(), 'gb-purge-guard-'));
    process.env.GBRAIN_HOME = homeParent;
    try {
      const cloneRoot = gbrainPath('clones');
      const sibling = join(cloneRoot, 'sibling-mirror-github');
      mkdirSync(sibling, { recursive: true });
      writeFileSync(join(sibling, 'page.md'), 'survives');

      // Corrupt row: local_path = the managed clone root itself. Pre-fix this
      // passed isPathContained (equality accepted) and rm -rf'd every mirror.
      const r1 = await purgeExpiredSources(purgeStubFor('corrupt-src', cloneRoot));
      expect(r1.purged).toEqual(['corrupt-src']);
      expect(existsSync(join(sibling, 'page.md'))).toBe(true);

      // Strictly contained but NOT the pinned '<id>-github' shape → refused.
      const r2 = await purgeExpiredSources(purgeStubFor('other-src', sibling));
      expect(r2.purged).toEqual(['other-src']);
      expect(existsSync(sibling)).toBe(true);

      // The exact gh_managed creation shape still gets cleaned up.
      const owned = join(cloneRoot, 'gone-src-github');
      mkdirSync(owned, { recursive: true });
      writeFileSync(join(owned, 'page.md'), 'removed');
      const r3 = await purgeExpiredSources(purgeStubFor('gone-src', owned));
      expect(r3.purged).toEqual(['gone-src']);
      expect(existsSync(owned)).toBe(false);
      expect(existsSync(cloneRoot)).toBe(true);
    } finally {
      if (prevHome === undefined) delete process.env.GBRAIN_HOME;
      else process.env.GBRAIN_HOME = prevHome;
      rmSync(homeParent, { recursive: true, force: true });
    }
  });
});