Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.6 KB
Raw Blame
/**
 * `gbrain repair provenance` (#7891, #7918): put back the provenance stamps and lowering markers that writes removed
 * before #7892, and stamp the trust marker on classified pages whose file would re-read higher than the row.
 * trust/provenance-drift.ts decides which pages and what each one gets; every change only lowers.
 *
 * - `restore` (class `remote`, or `ambiguous` with `--include-ambiguous`): the stamps restored, the lost cap stamped
 *   back as the `trust_tier` marker, the page lowered to min(stored, marker), and a `lower_page` proposal filed
 *   (`gbrain trust review` confirms or reverts it), through the owner page write `trust_owner_page` mode
 *   `restore_provenance` (trust/page-handlers.ts `restorePageProvenance`).
 * - `restamp` (#7918): the stored tier stamped as the marker; the row keeps its tier (mode `repair_marker`).
 * - Listed, never written: `needs_review` (a later local write also changed the stamp), `local` (the owner's own
 *   edit), `ambiguous` without the flag, and `held` (#8009): a page whose file sync holds, which an owner page write
 *   refuses (`pageHolds`, read by the preview and again by the apply, so the apply writes what the preview counted).
 *
 * Explicit-only and preview-bound: the preview lists each page with its revision and planned change under a hash and
 * writes nothing but the approval checkpoint; `--apply --expect <hash> --yes` writes exactly that set, one owner page
 * write per page, bound to the previewed revision and change (`preview_changed` when either moved). On a managed
 * brain the write publishes the canonical file through the coordinator (Git stays the parent); on a repo-less brain
 * the database is the record. Local CLI only. It never runs from `--all`, the remediation plan or an upgrade.
 */
import type { BrainEngine } from '../engine.ts';
import { OperationError, opError } from '../ops/contract.ts';
import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { GIT_HOLD_OP, gitHoldFix, type GitHoldRecord } from '../persistence/sync-holds.ts';
import { ownerRepairFile, repairPageMarker, restorePageProvenance } from '../trust/page-handlers.ts';
import { plannedDigest, readPageDrift, scanProvenanceDrift, type DriftItem } from '../trust/provenance-drift.ts';
import { afterCursor, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairListing, type RepairPlan, type RepairScope } from './core.ts';

const DOCS = 'docs/guides/repair.md#provenance';

interface Selection { source_ids: string[]; slugs: string[]; include_ambiguous: boolean }
interface PlannedPage { source_id: string; slug: string; id: number; revision: string; action: 'restore' | 'restamp'; planned: string; summary: string }
interface ProvenanceItem extends RepairItem { page: PlannedPage; hash: string; includeAmbiguous: boolean; last: boolean }

function previewCommand(scope: RepairScope, selection: Selection): string {
  return `gbrain repair provenance${scope.source_ids.length === 1 ? ` --source ${scope.source_ids[0]}` : ''}${selection.slugs.map(slug => ` --slug ${slug}`).join('')}`
    + (selection.include_ambiguous ? ' --include-ambiguous' : '');
}

const sourcesOf = (engine: BrainEngine, scope: RepairScope) => 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]);

const hashOf = async (engine: BrainEngine, scope: RepairScope, selection: Selection, pages: PlannedPage[]) =>
  previewHash({ kind: 'provenance-v1', brain_id: scope.brain_id, sources: await sourcesOf(engine, scope), selection,
    pages: pages.map(page => ({ source_id: page.source_id, id: page.id, revision: page.revision, action: page.action, planned: page.planned })) });

const describe = (value: unknown) => value === null || value === undefined ? '(none)' : String(value);

function summaryOf(item: DriftItem): string {
  const { verdict } = item;
  const restore = verdict.restore!;
  const stamps = Object.entries(restore.stamps).map(([key, value]) => {
    const live = verdict.changes.filter(change => change.key === key).at(-1)?.to;
    return `${key} ${describe(live)} -> ${describe(value)}`;
  });
  return [...stamps, `trust_tier marker -> ${describe(restore.marker)}`, `tier ${item.tier} -> ${restore.tier}`].join('; ');
}

function writerDetail(item: DriftItem): string {
  const change = item.verdict.changes.find(entry => entry.writer === item.verdict.writer) ?? item.verdict.changes[0];
  return change ? `written by a ${change.writer} write${change.request_id ? ` (request ${change.request_id})` : ''}` : '';
}

/** #8009: the sync holds of the source's live incarnation on these pages (by page id or slug), keyed by page id. */
async function pageHolds(engine: BrainEngine, sourceId: string, pages: ReadonlyArray<{ id: number; slug: string }>): Promise<Map<number, GitHoldRecord>> {
  if (!pages.length) return new Map();
  const holds = (await engine.executeRaw<{ record: GitHoldRecord }>(`SELECT h.completed_keys->0 AS record FROM op_checkpoints h
    JOIN sources s ON s.id=h.completed_keys->0->>'source_id' AND s.incarnation::text=h.completed_keys->0->>'incarnation'
    WHERE h.op=$1 AND s.id=$2 AND (h.completed_keys->0->>'slug'=ANY($3::text[]) OR h.completed_keys->0->>'page_id'=ANY($4::text[]))`,
  [GIT_HOLD_OP, sourceId, pages.map(page => page.slug), pages.map(page => String(page.id))])).map(row => row.record);
  return new Map(pages.flatMap(page => {
    const hold = holds.find(record => Number(record.page_id) === page.id || record.slug === page.slug);
    return hold ? [[page.id, hold] as const] : [];
  }));
}

const heldDetail = (hold: GitHoldRecord) => `sync holds the page file (${hold.code}), so a page write refuses it; resolve the hold (${(gitHoldFix(hold).argv ?? []).join(' ')}), then preview again`;

const segmented = async (engine: BrainEngine, pageId: number) =>
  (await engine.executeRaw<{ body_storage: string | null }>('SELECT body_storage FROM pages WHERE id = $1', [pageId]))[0]?.body_storage === 'segmented';

/** Every page of the selection the repair would write or list, 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> = { restore: 0, restamp: 0, ambiguous: 0, needs_review: 0, local: 0, held: 0 };
  const managedBrain = await managedPersistenceEnabled(engine);
  for (const sourceId of scope.source_ids) {
    const drift = await scanProvenanceDrift(engine, sourceId, { limit: Number.MAX_SAFE_INTEGER, includeAmbiguous: selection.include_ambiguous, slugs: selection.slugs });
    const holds = await pageHolds(engine, sourceId, drift.items.map(item => ({ id: item.page_id, slug: item.slug })));
    for (const item of drift.items) {
      const label = `${item.source_id}:${item.slug} (revision ${item.revision})`;
      const { verdict } = item;
      if (verdict.class === 'local') { residuals.local!++; listing.push({ item: label, class: 'local', detail: `the owner's own edit, never repaired; ${writerDetail(item)}` }); continue; }
      if (verdict.class === 'needs_review') { residuals.needs_review!++; listing.push({ item: label, class: 'needs_review', detail: `${verdict.reason}; edit the page by hand` }); continue; }
      if (!verdict.restore) {
        residuals.ambiguous!++;
        listing.push({ item: label, class: 'ambiguous', detail: `no recorded writer; previewed with --include-ambiguous only; ${writerDetail(item)}` });
        continue;
      }
      const hold = holds.get(item.page_id);
      if (hold) { residuals.held!++; listing.push({ item: label, class: 'held', detail: heldDetail(hold) }); continue; }
      if (await segmented(engine, item.page_id)) {
        residuals.needs_review!++;
        listing.push({ item: label, class: 'needs_review', detail: 'the page stores its body in segments, which this repair does not rewrite; edit its frontmatter by hand' });
        continue;
      }
      const file = managedBrain ? null : await ownerRepairFile(engine, item.source_id, item.slug);
      if (file && !file.ok) {
        residuals.needs_review!++;
        listing.push({ item: label, class: 'needs_review', detail: file.reason === 'file_database_drift'
          ? 'the page file holds an edit the database lacks; run gbrain sync first, then preview again'
          : `the page file cannot be written (${file.reason}); fix the checkout, then preview again` });
        continue;
      }
      const action = verdict.class === 'restamp' ? 'restamp' : 'restore';
      residuals[action]!++;
      const page: PlannedPage = { source_id: item.source_id, slug: item.slug, id: item.page_id, revision: item.revision, action, planned: plannedDigest(item), summary: summaryOf(item) };
      planned.push(page);
      listing.push({ item: label, class: action === 'restamp' ? 'restamp' : verdict.class, detail: action === 'restamp' ? page.summary : `${page.summary}; ${writerDetail(item)}` });
    }
  }
  planned.sort((a, b) => a.id - b.id);
  return { planned, listing, residuals };
}

function item(page: PlannedPage, hash: string, includeAmbiguous: boolean, last: boolean): ProvenanceItem {
  return { cursor: { phase: 0, id: page.id }, source_id: page.source_id, slug: page.slug, chars: 0, action: page.summary, page, hash, includeAmbiguous, last };
}

/** The page still needs exactly the previewed change. */
async function stillPlanned(engine: BrainEngine, page: PlannedPage, includeAmbiguous: boolean): Promise<'planned' | 'done' | 'moved'> {
  const current = await readPageDrift(engine, page.source_id, page.slug, { includeAmbiguous });
  if (!current) return 'done';
  if (current.page_id !== page.id || !current.verdict.restore) return 'moved';
  return current.revision === page.revision && plannedDigest(current) === page.planned ? 'planned' : 'moved';
}

export const provenanceRepair: RepairHandler = {
  kind: 'provenance',
  async plan(engine, scope, after, opts): Promise<RepairPlan> {
    const selection: Selection = { source_ids: scope.source_ids, slugs: [...new Set(opts?.slugs ?? [])].sort(), include_ambiguous: opts?.includeAmbiguous === true };
    const command = previewCommand(scope, selection);
    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: 'provenance', hash }, planned.map(page => ({ ...page, selection })));
      return { items: planned.map((page, index) => item(page, hash, selection.include_ambiguous, index === planned.length - 1)), preview_hash: hash, residuals, listing };
    }
    if (opts.remote !== false) {
      throw opError('permission_denied', 'gbrain repair provenance --apply runs only from the local CLI on the brain host.', `Run it there: ${command}`);
    }
    if (!opts.expect) {
      throw new OperationError('invalid_params', 'gbrain repair provenance --apply writes 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: 'provenance', hash: expect, previewCommand: command,
      emptyHash: () => hashOf(engine, scope, selection, []) })).items;
    const selectionKey = (value: Selection) => JSON.stringify([value.source_ids, value.slugs, value.include_ambiguous]);
    if (approved.some(page => selectionKey(page.selection) !== selectionKey(selection))) throw previewChangedError(expect, command);
    const pages: PlannedPage[] = [];
    // A page an earlier run of this apply already repaired is done; any other page must still need exactly the previewed change.
    for (const { selection: _selection, ...page } of approved) {
      const state = await stillPlanned(engine, page, selection.include_ambiguous);
      if (state === 'moved') throw previewChangedError(expect, command);
      if (state === 'planned') pages.push(page);
    }
    if (!pages.length) await clearApprovedSet(engine, { command: 'provenance', hash: expect });
    return { items: pages.map((page, index) => item(page, expect, selection.include_ambiguous, index === pages.length - 1)).filter(entry => afterCursor(entry.cursor, after)),
      preview_hash: expect, residuals: {} };
  },
  async apply(ctx, entry): Promise<RepairItemOutcome> {
    const { page, hash, includeAmbiguous, last } = entry as ProvenanceItem;
    return retireAfterLastItem(ctx.engine, 'provenance', hash, last, async () => {
      if (await stillPlanned(ctx.engine, page, includeAmbiguous) !== 'planned') return { applied: false, outcome: 'changed_since_preview', reason: 'the page changed since the preview' };
      const hold = (await pageHolds(ctx.engine, page.source_id, [page])).get(page.id);
      if (hold) return { applied: false, outcome: 'held', reason: heldDetail(hold) };
      const input = { sourceId: page.source_id, slug: page.slug, expectedRevision: page.revision, confirmation: { via: 'preview_hash' as const }, config: ctx.config };
      const result = page.action === 'restamp' ? await repairPageMarker(ctx.engine, input)
        : await restorePageProvenance(ctx.engine, { ...input, planned: page.planned, includeAmbiguous });
      return { applied: true, outcome: page.action === 'restamp' ? 'restamped' : 'restored', detail: { tier: result.tier, prior_tier: result.prior_tier } };
    });
  },
};