Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
3.9 KB
Raw Blame
/**
 * #6948: the database invariant behind origin twins: one live page per recorded origin, a partial unique index
 * `pages_live_origin_key` on (source_id, source_path) over live pages that record a file. It is built online only
 * when the brain holds no live twins (the migration, or `gbrain repair origin-twins --apply` once the last group is
 * resolved); with twins it is left pending and doctor names the repair, so no upgrade fails or rewrites data.
 * The index covers the stored spelling; the legacy `<scope>/<origin>` spelling of a scoped source-root source is
 * refused by the writer guard and reported by doctor and the repair.
 */
import type { BrainEngine } from '../engine.ts';
import { buildIndexOnline, type OnlineIndexOutcome } from '../schema-migrations/helpers.ts';

export const ORIGIN_INDEX = {
  name: 'pages_live_origin_key',
  table: 'pages',
  sql: 'CREATE UNIQUE INDEX IF NOT EXISTS pages_live_origin_key ON pages (source_id, source_path) WHERE deleted_at IS NULL AND source_path IS NOT NULL',
};

/** Live twin groups (same stored origin) per source, at most `limit` sources. */
export async function originTwinCounts(engine: Pick<BrainEngine, 'executeRaw'>, limit = 50): Promise<Array<{ source_id: string; groups: number; twins: number }>> {
  const rows = await engine.executeRaw<{ source_id: string; groups: number; twins: number }>(`SELECT source_id, count(*)::int AS groups, (sum(n) - count(*))::int AS twins
    FROM (SELECT source_id, count(*) AS n FROM pages WHERE deleted_at IS NULL AND source_path IS NOT NULL GROUP BY source_id, source_path HAVING count(*) > 1) g
    GROUP BY source_id ORDER BY source_id LIMIT ${Math.max(1, Math.floor(limit))}`);
  return rows.map(row => ({ source_id: row.source_id, groups: Number(row.groups), twins: Number(row.twins) }));
}

export type OriginIndexState = 'present' | 'missing' | 'invalid';

export async function originIndexState(engine: Pick<BrainEngine, 'executeRaw' | 'kind'>): Promise<OriginIndexState> {
  if (engine.kind !== 'postgres') {
    const [row] = await engine.executeRaw<{ present: boolean }>('SELECT to_regclass($1) IS NOT NULL AS present', [ORIGIN_INDEX.name]);
    return row?.present ? 'present' : 'missing';
  }
  const [row] = await engine.executeRaw<{ valid: boolean }>('SELECT indisvalid AS valid FROM pg_index WHERE indexrelid = to_regclass($1)', [ORIGIN_INDEX.name]);
  return !row ? 'missing' : row.valid ? 'present' : 'invalid';
}

export const originTwinsRepairCommand = (sourceId: string) => `gbrain repair origin-twins --source ${sourceId}`;

export type OriginIndexOutcome = { state: Exclude<OnlineIndexOutcome, 'building'> | 'building' } | { state: 'pending'; sources: Array<{ source_id: string; groups: number; twins: number }> };

/**
 * Builds the index when no live twins exist (online, CONCURRENTLY on Postgres); otherwise writes nothing and returns
 * the sources that still hold twins. A twin written between the check and a concurrent build fails the build: the
 * INVALID remnant (which would still enforce uniqueness) is dropped and the index stays pending. Never throws for twins.
 */
export async function buildOriginIndexIfClean(engine: BrainEngine, version: number, notice?: (line: string) => void): Promise<OriginIndexOutcome> {
  if (await originIndexState(engine) === 'present') return { state: 'present' };
  const sources = await originTwinCounts(engine);
  if (sources.length) return { state: 'pending', sources };
  try {
    return { state: await buildIndexOnline(engine, version, ORIGIN_INDEX, { notice, rebuild: 'gbrain repair origin-twins --source <id> --apply' }) };
  } catch (error) {
    const again = await originTwinCounts(engine);
    if (!again.length) throw error;
    if (engine.kind === 'postgres') await engine.withReservedConnection(conn => conn.executeRaw(`DROP INDEX CONCURRENTLY IF EXISTS ${ORIGIN_INDEX.name}`), { selfContained: true });
    else await engine.executeRaw(`DROP INDEX IF EXISTS ${ORIGIN_INDEX.name}`);
    return { state: 'pending', sources: again };
  }
}