Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.7 KB
Raw Blame
/**
 * Skipped backfill rows (GBRA-130 A-47): the durable record of rows a
 * `runBackfill` could not write, in config key `backfill.<name>.skipped`.
 *
 * A row whose compute or UPDATE fails with an item-scoped error is recorded
 * here before the checkpoint moves past it, so it is never skipped silently:
 * every later run retries each recorded row that still needs the backfill and
 * drops the record once the row lands or no longer matches. A content failure
 * (classifyItemFailure class `content`, such as a CHECK violation) on 3
 * consecutive runs at the same row revision (a hash of the selected columns)
 * and the same gbrain version is held: later runs report it without retrying
 * it until the row or the version changes, or `gbrain backfill <name> --fresh`
 * walks every pending row again. A transient failure is never held.
 */
import { createHash } from 'node:crypto';
import type { BrainEngine } from './engine.ts';
import type { ItemFailure } from './item-failure.ts';

export const BACKFILL_HOLD_RUNS = 3;

export interface BackfillSkipRecord {
  id: number;
  code: string;
  class: 'content' | 'transient';
  message: string;
  /** Hash of the row's selected columns when it last failed. */
  revision: string;
  /** The gbrain version that last attempted it. */
  producer: string;
  /** Consecutive runs that failed it at this revision, version and class. */
  attempts: number;
  state: 'failing' | 'held';
  first_failed_at: string;
  last_failed_at: string;
}

export interface BackfillSkipLedger { version: 1; items: Record<string, BackfillSkipRecord> }

/** One recorded row as a backfill result reports it; `fix` is the command that retries it. */
export interface BackfillSkip {
  key: string;
  id: number;
  code: string;
  class: 'content' | 'transient';
  state: 'failing' | 'held';
  attempts: number;
  message: string;
  fix: string;
}

export function skipLedgerKey(name: string): string {
  return `backfill.${name}.skipped`;
}

/** The stored ledger as text (null when absent): runBackfill restores it exactly when a run stops systemic. */
export async function readSkipLedgerRaw(engine: BrainEngine, name: string): Promise<string | null> {
  const rows = await engine.executeRaw<{ value: string }>('SELECT value FROM config WHERE key = $1 LIMIT 1', [skipLedgerKey(name)]);
  return rows[0]?.value ?? null;
}

export function parseSkipLedger(raw: string | null): BackfillSkipLedger {
  try {
    const parsed = raw ? JSON.parse(raw) as Partial<BackfillSkipLedger> : null;
    if (parsed?.version === 1 && parsed.items && typeof parsed.items === 'object') return { version: 1, items: parsed.items };
  } catch { /* an unreadable ledger is treated as empty; the next write replaces it */ }
  return { version: 1, items: {} };
}

export async function restoreSkipLedger(engine: BrainEngine, name: string, raw: string | null): Promise<void> {
  if (raw === null) await engine.executeRaw('DELETE FROM config WHERE key = $1', [skipLedgerKey(name)]);
  else await engine.setConfig(skipLedgerKey(name), raw);
}

export function rowRevision(row: unknown): string {
  return createHash('sha256').update(JSON.stringify(row)).digest('hex').slice(0, 16);
}

/** A held record whose row and gbrain version are unchanged: reported, not retried. */
export function heldUnchanged(record: BackfillSkipRecord | undefined, revision: string, producer: string): boolean {
  return record?.state === 'held' && record.revision === revision && record.producer === producer;
}

/** Counts one run's failure of a row: consecutive at the same revision, version and class; held at BACKFILL_HOLD_RUNS content failures. */
export function noteSkip(ledger: BackfillSkipLedger, id: number, revision: string, failure: ItemFailure, now: string, producer: string): void {
  const prev = ledger.items[String(id)];
  const consecutive = prev && prev.revision === revision && prev.producer === producer && prev.class === failure.class;
  const attempts = consecutive ? prev.attempts + 1 : 1;
  ledger.items[String(id)] = {
    id, code: failure.code, class: failure.class, message: failure.message.slice(0, 300), revision, producer, attempts,
    state: failure.class === 'content' && attempts >= BACKFILL_HOLD_RUNS ? 'held' : 'failing',
    first_failed_at: consecutive ? prev.first_failed_at : now, last_failed_at: now,
  };
}

export function reportSkips(ledger: BackfillSkipLedger, name: string): BackfillSkip[] {
  return Object.values(ledger.items).sort((a, b) => a.id - b.id).map(record => ({
    key: String(record.id), id: record.id, code: record.code, class: record.class, state: record.state, attempts: record.attempts,
    message: record.message, fix: record.state === 'held' ? `gbrain backfill ${name} --fresh` : `gbrain backfill ${name}`,
  }));
}