Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.1 KB
Raw Blame
import type { BrainEngine } from './engine.ts';
import { opError } from './ops/contract.ts';
import { readFix } from './ops/op-fix.ts';

/**
 * An archived source is purge-eligible only when both archive timestamps are real
 * and its window has elapsed. A missing or epoch timestamp (#5452) cannot prove the
 * 72h recovery window was honored, so it never reads as expired.
 */
export const EXPIRED_ARCHIVE_SQL = `archived = true AND archived_at > '1970-01-02'::timestamptz
  AND archive_expires_at > '1970-01-02'::timestamptz AND archive_expires_at <= now()`;
export const UNVERIFIED_ARCHIVE_SQL = `archived = true AND (archived_at IS NULL OR archived_at <= '1970-01-02'::timestamptz
  OR archive_expires_at IS NULL OR archive_expires_at <= '1970-01-02'::timestamptz)`;
export const unverifiedArchiveReason = (id: string) =>
  `archive timestamps are missing or invalid, so the 72h recovery window cannot be verified; run gbrain sources restore ${id}, then gbrain sources archive ${id} to restart it`;

/**
 * #7072: a source delete removes its pages only through the pages -> sources
 * ON DELETE CASCADE. True when that cascade fires on this brain: the foreign key
 * exists on pages.source_id, cascades, and its delete trigger on sources is enabled
 * for this session. Where it does not, a delete would leave the pages live with no
 * sources row, unwritable and outside every per-source audit.
 */
const PAGES_CASCADE_SQL = `EXISTS (
  SELECT 1 FROM pg_constraint c JOIN pg_trigger t ON t.tgconstraint = c.oid AND t.tgrelid = c.confrelid
   WHERE c.contype = 'f' AND c.conrelid = 'pages'::regclass AND c.confrelid = 'sources'::regclass AND c.confdeltype = 'c'
     AND c.conkey = ARRAY[(SELECT a.attnum FROM pg_attribute a WHERE a.attrelid = 'pages'::regclass AND a.attname = 'source_id')]
     AND t.tgfoid = 'pg_catalog."RI_FKey_cascade_del"'::regproc
     AND (t.tgenabled = 'A' OR (t.tgenabled = 'O' AND current_setting('session_replication_role') <> 'replica')))`;

/**
 * Delete a `sources` row together with that incarnation's persistence source
 * binding (#5732). `persistence_source_bindings` has no FK to `sources`, so a
 * delete that leaves the binding would make a same-id replacement read as
 * claimed. A binding of another incarnation is never touched here; `gbrain
 * repair orphan-bindings` removes those. The source's managed-sync cursors
 * (`op_checkpoints`, also no FK) go too (#8741): nothing can resume them, and doctor `managed_sync_backlog` would warn with a resume command
 * that fails `unknown_source`. The same statement runs
 * removedSourceScrubCtes, and a second statement repeats it once the row is
 * gone, unless a source with this id exists again by then: a replacement
 * created between the two statements keeps its rows. A source that still has
 * pages is deleted only when the pages cascade (#7072), in the same statement;
 * otherwise nothing is deleted and `source_pages_remain` is thrown. Returns whether a row
 * was deleted.
 */
export async function deleteSourceRow(
  engine: Pick<BrainEngine, 'executeRaw'>,
  id: string,
  opts: { expiredArchiveOnly?: boolean } = {},
): Promise<boolean> {
  const expired = opts.expiredArchiveOnly
    ? `AND ${EXPIRED_ARCHIVE_SQL}`
    : '';
  const rows = await engine.executeRaw<{ id: string | null; stranded: number }>(
    `WITH stranded AS (SELECT count(*)::int AS n FROM pages WHERE source_id = $1 AND NOT ${PAGES_CASCADE_SQL}),
       gone AS (DELETE FROM sources WHERE id = $1 ${expired} AND (SELECT n FROM stranded) = 0 RETURNING id, incarnation),
       unbound AS (DELETE FROM persistence_source_bindings b USING gone
                    WHERE b.source_id = gone.id AND b.source_incarnation = gone.incarnation),
       cursors AS (DELETE FROM op_checkpoints c USING gone
                    WHERE c.op = 'managed-sync' AND c.completed_keys->0->>'sourceId' = gone.id),
       ${removedSourceScrubCtes('EXISTS (SELECT 1 FROM gone)')}
     SELECT id, 0 AS stranded FROM gone
     UNION ALL SELECT NULL, n FROM stranded WHERE n > 0 AND EXISTS (SELECT 1 FROM sources WHERE id = $1 ${expired})`,
    [id],
  );
  const stranded = rows.find(row => row.id === null);
  if (stranded) throw sourcePagesRemain(id, Number(stranded.stranded));
  if (!rows.length) return false;
  await engine.executeRaw(`WITH ${removedSourceScrubCtes('NOT EXISTS (SELECT 1 FROM sources WHERE id = $1)')} SELECT 1`, [id]);
  return true;
}

/**
 * #9068: CTEs that remove what names a removed source's pages outside a foreign key, for source `$1`, each only
 * when `gate` holds: the source's retrieval_event_pages, retrieval_event_links, retrieval_feedback and
 * context_volunteer_events rows, and each eval candidate's captured slugs that no other source the candidate covers
 * still has a page for (retrieval_weights and mention_gazetteer_entries cascade from sources). #9146: also the
 * source's core_edit_notices and write_gate_holds with the holds' receipts (take_proposals, open_loops, page_aliases,
 * slug_aliases and slug_rename_history cascade from sources). Every removal runs
 * them in the statement that deletes the sources row (gated on that delete), so the source and those rows go
 * together, then again in a later statement: that statement reads past a feedback write or eval capture that held one
 * of the source's page rows while the delete waited for it (a later one finds no page).
 */
export function removedSourceScrubCtes(gate: string): string {
  const deletes = ['retrieval_event_pages', 'retrieval_event_links', 'retrieval_feedback', 'context_volunteer_events', 'core_edit_notices']
    .map(table => `scrub_${table} AS (DELETE FROM ${table} WHERE source_id = $1 AND ${gate})`);
  const holds = [`scrub_write_gate_holds AS (DELETE FROM write_gate_holds WHERE source_id = $1 AND ${gate} RETURNING id::text AS id)`,
    `scrub_write_gate_receipts AS (DELETE FROM write_gate_receipts r USING scrub_write_gate_holds h WHERE r.target_table = 'write_gate_holds' AND r.target_id = h.id)`];
  const elsewhere = (slug: string) => `EXISTS (SELECT 1 FROM pages pg WHERE pg.slug = ${slug} AND pg.source_id = ANY(c.source_ids) AND pg.source_id <> $1)`;
  return [...deletes, ...holds, `scrub_eval_candidates AS (UPDATE eval_candidates c
      SET retrieved_slugs = ARRAY(SELECT u.s FROM unnest(c.retrieved_slugs) WITH ORDINALITY AS u(s, n) WHERE ${elsewhere('u.s')} ORDER BY u.n)
      WHERE $1 = ANY(c.source_ids) AND EXISTS (SELECT 1 FROM unnest(c.retrieved_slugs) AS r(s) WHERE NOT ${elsewhere('r.s')}) AND ${gate})`].join(',\n       ');
}

function sourcePagesRemain(id: string, n: number) {
  return opError('source_pages_remain', `Deleting source '${id}' would leave ${n} page(s) with no source row, so nothing was deleted.`,
    `The database would not cascade the delete of source '${id}' to its ${n} page(s): the pages -> sources foreign key on this brain is missing, does not cascade or is disabled. `
    + `The source and its pages are unchanged. Keep the source (if it is archived, gbrain sources restore ${id} makes it active again) and give the brain host's operator the output of the command in fix.`,
    { fix: { ...readFix('Reports the brain\'s schema and health, read-only.', { argv: ['gbrain', 'doctor', '--json'] }), actor: 'host_admin' } });
}