Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.0 KB
Raw Blame
/**
 * `gbrain repair contact-rows` (#8109): collapse duplicated frontmatter contact
 * rows. A writer that appended a `{type, value, last_used}` row on every touch
 * instead of updating the existing one left the same value many times; the
 * repair keeps one row per (type, value) with the newest `last_used`
 * (`dedupeContactRows`, contact-rows.ts), and never drops a distinct value.
 *
 * Explicit-only and preview-bound: the preview lists each page with its
 * revision and row counts under a hash and writes nothing but the approval
 * checkpoint; `--apply --expect <hash> --yes` publishes exactly that set, one
 * revision-bound `put_page` per page with a request id derived from the hash,
 * so a source with a checkout commits the canonical file through the
 * coordinated writer and a database-only (repo-less) source writes the
 * database. Only the `contacts` frontmatter key changes. A page whose canonical
 * file differs from the database is listed `needs_reconcile` with the
 * `--auto-additive` reconcile command (a `last_used`-only drift is
 * structurally additive), never written. Segmented pages are left alone. It
 * never runs from `--all`, the remediation plan, maintenance or an upgrade.
 */
import type { BrainEngine, PageSnapshot } from '../engine.ts';
import { OperationError } from '../ops/contract.ts';
import { parseMarkdown, serializePageToMarkdown } from '../markdown.ts';
import { dedupeFrontmatterContacts } from '../contact-rows.ts';
import { digest } from '../persistence/digest.ts';
import { liveFileDrift } from '../persistence/drift-conflicts.ts';
import { submitPageMutation } from '../persistence/page-mutations.ts';
import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
import { afterCursor, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairListing, type RepairPlan, type RepairScope } from './core.ts';

const BATCH = 200;
const DOCS = 'docs/guides/repair.md#contact-rows';

interface Selection { source_ids: string[]; slugs: string[] }
interface PlannedPage { source_id: string; slug: string; id: number; revision: string; rows_before: number; rows_after: number }
interface RowsItem extends RepairItem { page: PlannedPage; hash: string; last: boolean }

function previewCommand(scope: RepairScope, slugs: string[]): string {
  return `gbrain repair contact-rows${scope.source_ids.length === 1 ? ` --source ${scope.source_ids[0]}` : ''}${slugs.map(slug => ` --slug ${slug}`).join('')}`;
}

const hashOf = async (engine: BrainEngine, scope: RepairScope, selection: Selection, pages: PlannedPage[]) => previewHash({ kind: 'contact-rows-v1', brain_id: scope.brain_id,
  sources: await engine.executeRaw<{ id: string; incarnation: string }>('SELECT id, incarnation::text AS incarnation FROM sources WHERE id=ANY($1::text[]) ORDER BY id', [scope.source_ids]),
  selection, pages });

/** One request id per page of an approved set: a resumed apply replays it, and the plan knows which pages already published. */
function requestIdOf(hash: string, page: Pick<PlannedPage, 'source_id' | 'slug' | 'revision'>): string {
  const h = digest(['contact-rows-request-v1', hash, page.source_id, page.slug, page.revision]);
  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-a${h.slice(17, 20)}-${h.slice(20, 32)}`;
}

/** The page's repaired file, or null when its contact rows need no change or the rendered page would not read back with exactly those rows. */
function plannedChange(snapshot: PageSnapshot): { content: string; rows_before: number; rows_after: number } | null {
  const { page, tags } = snapshot;
  const deduped = dedupeFrontmatterContacts(page.frontmatter);
  if (!deduped) return null;
  const content = serializePageToMarkdown({ ...page, frontmatter: deduped.frontmatter }, tags);
  const reread = parseMarkdown(content, `${page.slug}.md`);
  const { contacts: _after, ...restAfter } = reread.frontmatter;
  const { contacts: _before, ...restBefore } = page.frontmatter;
  if (digest(reread.frontmatter.contacts) !== digest(deduped.dedupe.rows) || digest(restAfter) !== digest(restBefore)
    || reread.compiled_truth.trim() !== page.compiled_truth.trim() || (reread.timeline ?? '').trim() !== (page.timeline ?? '').trim()) return null;
  return { content, rows_before: (page.frontmatter.contacts as unknown[]).length, rows_after: deduped.dedupe.rows.length };
}

const reconcileCommand = (page: Pick<PlannedPage, 'source_id' | 'slug'>) => `gbrain sources reconcile ${page.source_id} ${page.slug} --brain host --preview --auto-additive`;

/** Every inline page of the selection whose contact rows the repair would collapse, in id order. Read-only. */
async function scan(engine: BrainEngine, scope: RepairScope, selection: Selection) {
  const planned: PlannedPage[] = [];
  const listing: RepairListing[] = [];
  const residuals: Record<string, number> = { pages_to_dedupe: 0, rows_to_remove: 0, needs_reconcile: 0 };
  for (let cursor = 0; ;) {
    const batch = await engine.executeRaw<{ id: number; source_id: string; slug: string }>(
      `SELECT id, source_id, slug FROM pages
        WHERE source_id=ANY($1::text[]) AND deleted_at IS NULL AND body_storage='inline' AND id>$2
          AND CASE WHEN jsonb_typeof(frontmatter->'contacts')='array' THEN jsonb_array_length(frontmatter->'contacts') ELSE 0 END>1
          AND (cardinality($3::text[])=0 OR slug=ANY($3::text[]))
        ORDER BY id LIMIT ${BATCH}`, [scope.source_ids, cursor, selection.slugs]);
    for (const row of batch) {
      cursor = Number(row.id);
      const snapshot = await engine.readPageSnapshot(row.slug, { sourceId: row.source_id });
      const change = snapshot && plannedChange(snapshot);
      if (!snapshot || !change) continue;
      const page = { source_id: row.source_id, slug: row.slug, id: Number(row.id), revision: snapshot.revision, rows_before: change.rows_before, rows_after: change.rows_after };
      const label = `${row.source_id}:${row.slug} (revision ${snapshot.revision})`;
      if ((await liveFileDrift(engine, row.source_id, row.slug, snapshot)).still_present === true) {
        residuals.needs_reconcile!++;
        listing.push({ item: label, class: 'needs_reconcile', detail: `its canonical file differs from the database; preview ${reconcileCommand(page)}, apply it, then preview this repair again` });
        continue;
      }
      planned.push(page);
      residuals.pages_to_dedupe!++;
      residuals.rows_to_remove! += page.rows_before - page.rows_after;
      listing.push({ item: label, class: 'dedupe', detail: `${page.rows_before} contact rows become ${page.rows_after}` });
    }
    if (batch.length < BATCH) return { planned, listing, residuals };
  }
}

function item(page: PlannedPage, hash: string, last: boolean): RowsItem {
  return { cursor: { phase: 0, id: page.id }, source_id: page.source_id, slug: page.slug, chars: 0, action: `collapses ${page.rows_before} contact rows to ${page.rows_after}`, page, hash, last };
}

export const contactRowsRepair: RepairHandler = {
  kind: 'contact-rows',
  async plan(engine, scope, after, opts): Promise<RepairPlan> {
    const selection: Selection = { source_ids: scope.source_ids, slugs: [...new Set(opts?.slugs ?? [])].sort() };
    const command = previewCommand(scope, selection.slugs);
    if (!opts?.apply) {
      const { planned, listing, residuals } = await scan(engine, scope, selection);
      const hash = await hashOf(engine, scope, selection, planned);
      if (planned.length) await saveApprovedSet<PlannedPage & { selection: Selection }>(engine, { command: 'contact-rows', hash }, planned.map(page => ({ ...page, selection })));
      return { items: planned.map((page, index) => item(page, hash, index === planned.length - 1)), preview_hash: hash, residuals, listing };
    }
    if (!opts.expect) {
      throw new OperationError('invalid_params', 'gbrain repair contact-rows --apply rewrites only the set a preview printed.',
        `Preview first: ${command} — show the user the listing, then run the apply command it prints: ${command} --apply --expect <preview-hash> --yes`, DOCS);
    }
    const expect = opts.expect;
    const approved = (await loadApprovedSet<PlannedPage & { selection: Selection }>(engine, { command: 'contact-rows', hash: expect, previewCommand: command,
      emptyHash: () => hashOf(engine, scope, selection, []) })).items;
    if (approved.some(page => digest(page.selection) !== digest(selection))) throw previewChangedError(expect, command);
    const pages = approved.map(({ selection: _selection, ...page }) => page);
    const published = new Set((await engine.executeRaw<{ request_id: string }>(
      "SELECT request_id::text AS request_id FROM persistence_requests WHERE request_id=ANY($1::uuid[]) AND state='committed'",
      [pages.map(page => requestIdOf(expect, page))])).map(row => row.request_id));
    // Every page not yet published under this hash still has the revision the user saw, or nothing is written.
    for (const page of pages) {
      if (published.has(requestIdOf(expect, page))) continue;
      const snapshot = await engine.readPageSnapshot(page.slug, { sourceId: page.source_id });
      if (snapshot?.revision !== page.revision || Number(snapshot.page.id) !== page.id) throw previewChangedError(expect, command);
    }
    return { items: pages.map((page, index) => item(page, expect, index === pages.length - 1)).filter(entry => afterCursor(entry.cursor, after)),
      preview_hash: expect, residuals: {} };
  },
  async apply(ctx, entry): Promise<RepairItemOutcome> {
    const { page, hash, last } = entry as RowsItem;
    try {
      const requestId = requestIdOf(hash, page);
      const detail = { rows_before: page.rows_before, rows_after: page.rows_after };
      const [done] = await ctx.engine.executeRaw<{ state: string }>('SELECT state FROM persistence_requests WHERE request_id=$1::uuid', [requestId]);
      if (done?.state === 'committed') return { applied: true, outcome: 'deduped', detail };
      const snapshot = await ctx.engine.readPageSnapshot(page.slug, { sourceId: page.source_id });
      if (!snapshot || snapshot.revision !== page.revision) return { applied: false, outcome: 'changed_since_preview', reason: 'the page changed since the preview' };
      const change = plannedChange(snapshot);
      if (!change) return { applied: false, outcome: 'changed_since_preview', reason: 'the contact rows need no change' };
      try {
        await submitPageMutation(ctx, { operation: 'put_page', params: { slug: page.slug, source_id: page.source_id, content: change.content,
          expected_revision: snapshot.revision, request_id: requestId } });
      } catch (error) {
        if (!(error instanceof OperationError) || error.code !== 'source_changed' || error.detail !== 'file_database_drift') throw error;
        return { applied: false, outcome: 'needs_reconcile', reason: `the canonical file differs from the database; preview ${reconcileCommand(page)}, apply it, then preview this repair again` };
      }
      return { applied: true, outcome: 'deduped', detail };
    } finally {
      if (last) await clearApprovedSet(ctx.engine, { command: 'contact-rows', hash });
    }
  },
};