Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
27.1 KB
Raw Blame
/**
 * `gbrain repair extractor-facts` (#5731, CEO-A9, ENG-O8, DX-O4, DX-T1):
 * restore conversation-extractor facts that the pre-fix canonical projection
 * expired.
 *
 * Before v0.60.11.0 every managed write to a fenceless conversation page ran
 * the canonical facts projection with an empty fence, which expired every
 * extractor fact of that page and cleared its `row_num` in the publication
 * transaction. The fix stopped new expiries; this kind restores the old ones.
 *
 * Candidates: `source` starts with `cli:extract-conversation-facts`,
 * `expired_at` set, `row_num` NULL (the projection's signature), and not
 * retired by `gbrain repair conversation-labels` (its context marker). Each is
 * classified, in this order:
 *   - excluded (listed, never restored): the page is missing or deleted; the
 *     fact was superseded (`superseded_by`, E-T5); its claim was withdrawn
 *     (`fact_withdrawals`); an active fact with the same text and entity already
 *     sits on the page (a fence row or another extractor row); or another
 *     candidate of the page with the same text and entity is restored instead
 *     (the first evidenced one, else the first ambiguous one).
 *   - ambiguous (restored only with `--include-ambiguous` and the hash of that
 *     preview): an unmanaged brain (no receipts); no committed write receipt of
 *     the page completed at the exact expiry instant (`completed_at =
 *     expired_at`, which holds only when both happened in one transaction); the
 *     receipt's consumer is v0.60.11.0 or newer (a fence takeover, not the
 *     defect); or the page ever carried fence-projected facts (a fence row may
 *     have taken the fact's row number).
 *   - evidenced: everything else, restored by `--apply --expect <hash>`.
 *
 * `writer_version_cutoff` marks when consumers began stamping their version,
 * so a receipt with no `consumer_version` was published by a binary older
 * than the stamps, which shipped together with the fix.
 *
 * The preview lists every candidate with its class and evidence, prints a
 * hash over them, and saves the restorable set (one item per page, each with
 * its request id) through `persistence/preview-approval.ts`. The apply replays
 * exactly that set: a managed brain publishes one database-only
 * `managed_maintenance_restore_extractor_facts` request per page; an unmanaged
 * brain writes directly under the page lock. Each fact is reclassified under
 * the lock and restored only when its class, evidence and expiry are
 * unchanged (`changed_since_preview` otherwise). A restored fact gets a fresh
 * `row_num` above every row of its page, so it never looks like an unfenced
 * legacy row. A resumed apply skips pages whose request already committed (or
 * whose facts are already active), so a crash after publication restores no
 * new candidate. A page already passed by this set's cursor (keyed by its
 * approval hash) is not retried,
 * whatever its outcome, so a `--limit` run always advances.
 */
import type { BrainEngine } from '../engine.ts';
import type { PreparedMutation } from '../persistence/coordinator.ts';
import type { WriteRequest } from '../persistence/model.ts';
import { VERSION } from '../../version.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { parseFactsFence } from '../facts-fence.ts';
import { digest } from '../persistence/digest.ts';
import { isTerminal } from '../persistence/model.ts';
import { getWriteRequest } from '../persistence/journal.ts';
import { authorizeStoredRequest, authorizeWrite } from '../persistence/authority.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { waitForWrite, writeResponse } from '../persistence/service.ts';
import { maintenancePreflight, submitDatabaseMaintenanceIntent } from '../persistence/prepared-maintenance.ts';
import { compareWriterVersions, recentWriterVersions, writerVersionLabel } from '../persistence/writer-versions.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';
import { maintenanceTransaction } from '../persistence/attribution.ts';

export const EXTRACTOR_FACTS_INTENT = 'managed_maintenance_restore_extractor_facts';
export const EXTRACTOR_FACTS_SOURCE_PREFIX = 'cli:extract-conversation-facts';
const extractorPreviewFix = (sourceId: string) => readFix('Previews the extractor-facts repair without changing anything.',
  { argv: ['gbrain', 'repair', 'extractor-facts', '--source', sourceId, '--json'] });

/** The first release whose canonical projection leaves fenceless extractor facts alone. */
export const EXTRACTOR_FACTS_FIX_VERSION = '0.60.11.0';

export type ExtractorFactClass = 'evidenced' | 'ambiguous' | 'excluded';

/**
 * The exact expiry instant as text (UTC, microseconds). Compared as text in
 * SQL: a bound timestamp parameter can lose its microseconds on the way in.
 */
const EXPIRY_TEXT = (column: string) => `to_char(${column} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`;

/** One candidate as the preview showed it; the apply rechecks every field. */
export interface ExtractorFactCandidate {
  id: number;
  source_id: string;
  slug: string;
  class: ExtractorFactClass;
  reason: string;
  /** UTC, microseconds: the exact instant the projection expired it. */
  expired_at: string;
  /** The committed request whose publication expired it, if any. */
  receipt: string | null;
  receipt_consumer: string | null;
  /** Digest of the row's claim, visibility and entity, so an edited row is not restored. */
  fact_hash: string;
}

/** One approved page: its restorable facts and the request id its managed restore uses. */
export interface ExtractorFactsPage {
  source_id: string;
  slug: string;
  page_id: number;
  request_id: string;
  include_ambiguous: boolean;
  /** The preview's source scope; an apply under another scope refuses. */
  scope: string[];
  facts: ExtractorFactCandidate[];
}

interface PageItem extends RepairItem { page: ExtractorFactsPage; hash: string; last: boolean }

interface CandidateRow {
  id: number | string; source_id: string; slug: string; fact: string; visibility: string; entity_slug: string | null;
  superseded: boolean; expired_at: string; page_id: number | string | null; page_deleted: boolean | null;
  withdrawn: boolean; active_duplicate: boolean; fence_history: boolean; fingerprint: string;
  receipt: string | null; receipt_consumer: string | null;
}

/**
 * Every candidate of these sources (or of one page), classified, in (source,
 * page, id) order. Read-only; `managed` is the brain's persistence mode.
 */
export async function classifyExtractorFacts(db: BrainEngine, sourceIds: string[], opts: { managed: boolean; slug?: string }): Promise<ExtractorFactCandidate[]> {
  const rows = await db.executeRaw<CandidateRow>(`
    WITH cand AS (
      SELECT f.id, f.source_id, f.source_markdown_slug AS slug, f.fact, f.visibility, f.entity_slug, f.expired_at AS expired,
             f.superseded_by IS NOT NULL AS superseded, gbrain_fact_fingerprint(f.fact) AS fingerprint
        FROM facts f
       WHERE f.source_id=ANY($1::text[]) AND f.source LIKE '${EXTRACTOR_FACTS_SOURCE_PREFIX}%'
         AND f.expired_at IS NOT NULL AND f.row_num IS NULL AND f.source_markdown_slug IS NOT NULL
         AND COALESCE(f.context, '') NOT LIKE '%retired: conversation-labels%'
         AND ($2::text IS NULL OR f.source_markdown_slug=$2::text)
    ), receipts AS (
      SELECT DISTINCT ON (r.source_id, r.slug, r.completed_at) r.source_id, r.slug, r.completed_at,
             r.request_id::text AS request_id, r.consumer_version
        FROM persistence_requests r
        JOIN (SELECT DISTINCT source_id, slug, expired FROM cand) k
          ON k.source_id=r.source_id AND k.slug=r.slug AND k.expired=r.completed_at
       WHERE r.state='committed'
       ORDER BY r.source_id, r.slug, r.completed_at, r.sequence
    ), fenced AS (
      SELECT DISTINCT g.source_id, g.source_markdown_slug AS slug FROM facts g
        JOIN (SELECT DISTINCT source_id, slug FROM cand) k ON k.source_id=g.source_id AND k.slug=g.source_markdown_slug
       WHERE COALESCE(g.source,'') NOT LIKE '${EXTRACTOR_FACTS_SOURCE_PREFIX}%'
    )
    SELECT c.id, c.source_id, c.slug, c.fact, c.visibility, c.entity_slug, c.superseded, c.fingerprint,
           ${EXPIRY_TEXT('c.expired')} AS expired_at,
           p.id AS page_id, p.deleted_at IS NOT NULL AS page_deleted,
           EXISTS (SELECT 1 FROM fact_withdrawals w WHERE w.source_id=c.source_id AND w.visibility=c.visibility
             AND w.fact_hash IN (gbrain_fact_fingerprint(c.fact), gbrain_fact_fingerprint_v1(c.fact))
             AND (w.subject='*' OR w.subject=c.entity_slug)) AS withdrawn,
           EXISTS (SELECT 1 FROM facts a WHERE a.source_id=c.source_id AND a.visibility=c.visibility
             AND gbrain_fact_fingerprint(a.fact)=c.fingerprint AND a.source_markdown_slug=c.slug AND a.expired_at IS NULL
             AND a.entity_slug IS NOT DISTINCT FROM c.entity_slug) AS active_duplicate,
           fenced.slug IS NOT NULL AS fence_history,
           r.request_id AS receipt, r.consumer_version AS receipt_consumer
      FROM cand c
      LEFT JOIN pages p ON p.source_id=c.source_id AND p.slug=c.slug
      LEFT JOIN receipts r ON r.source_id=c.source_id AND r.slug=c.slug AND r.completed_at=c.expired
      LEFT JOIN fenced ON fenced.source_id=c.source_id AND fenced.slug=c.slug
     ORDER BY c.source_id, c.slug, c.id`, [sourceIds, opts.slug ?? null]);
  // One representative per (page, visibility, entity, text): the first evidenced row, else the first ambiguous one.
  const key = (row: CandidateRow) => JSON.stringify([row.source_id, row.slug, row.visibility, row.entity_slug, row.fingerprint]);
  const base = rows.map(row => classify(row, false, opts.managed));
  const representative = new Map<string, number>();
  for (const klass of ['evidenced', 'ambiguous'] as const) {
    rows.forEach((row, i) => { if (base[i][0] === klass && !representative.has(key(row))) representative.set(key(row), i); });
  }
  return rows.map((row, i) => {
    const id = Number(row.id);
    const duplicate = base[i][0] !== 'excluded' && representative.get(key(row)) !== i;
    const [klass, reason] = duplicate ? classify(row, true, opts.managed) : base[i];
    return { id, source_id: row.source_id, slug: row.slug, class: klass, reason, expired_at: row.expired_at,
      receipt: row.receipt, receipt_consumer: row.receipt === null ? null : row.receipt_consumer,
      fact_hash: digest([row.fact, row.visibility, row.entity_slug]) };
  });
}

function classify(row: CandidateRow, duplicate: boolean, managed: boolean): [ExtractorFactClass, string] {
  if (row.page_id === null || row.page_deleted) return ['excluded', 'page_missing'];
  if (row.superseded) return ['excluded', 'superseded'];
  if (row.withdrawn) return ['excluded', 'withdrawn'];
  if (row.active_duplicate) return ['excluded', 'active_duplicate'];
  if (duplicate) return ['excluded', 'duplicate_candidate'];
  if (!managed) return ['ambiguous', 'unmanaged_brain'];
  if (row.receipt === null) return ['ambiguous', 'no_same_transaction_receipt'];
  const order = row.receipt_consumer === null ? -1 : compareWriterVersions(row.receipt_consumer, EXTRACTOR_FACTS_FIX_VERSION);
  if (order === null || order >= 0) return ['ambiguous', 'post_fix_consumer'];
  if (row.fence_history) return ['ambiguous', 'fence_takeover_possible'];
  return ['evidenced', 'pre_fix_projection'];
}

const DETAILS: Record<string, string> = {
  page_missing: 'its conversation page is missing or deleted',
  superseded: 'a newer fact superseded it',
  withdrawn: 'its claim was withdrawn (forget)',
  active_duplicate: 'an active fact with the same text and entity is already on the page',
  duplicate_candidate: 'another candidate of the page with the same text and entity is restored instead',
  unmanaged_brain: 'unmanaged brain: no write receipt can prove the expiry',
  no_same_transaction_receipt: 'no committed write of the page completed at the exact expiry instant',
  post_fix_consumer: 'expired by a write published by a fixed consumer (a fence row may have taken its position)',
  fence_takeover_possible: 'the page has carried fence facts, so a fence row may have taken its position',
};

function detail(fact: ExtractorFactCandidate): string {
  if (fact.class !== 'evidenced') return DETAILS[fact.reason] ?? fact.reason;
  return `expired at ${fact.expired_at} by the pre-fix projection in write ${fact.receipt}, published by ${writerVersionLabel(fact.receipt_consumer)}`;
}

/** The preview command for this scope: `--source` only when the scope is one source of several (what the operator passed). */
async function previewCommand(engine: BrainEngine, scope: RepairScope, includeAmbiguous: boolean): Promise<string> {
  const [{ n }] = await engine.executeRaw<{ n: number | string }>('SELECT count(*)::int AS n FROM sources WHERE archived IS NOT TRUE');
  const narrowed = scope.source_ids.length === 1 && Number(n) > 1;
  return `gbrain repair extractor-facts${narrowed ? ` --source ${scope.source_ids[0]}` : ''}${includeAmbiguous ? ' --include-ambiguous' : ''}`;
}

function requestIdFor(hash: string, page: Pick<ExtractorFactsPage, 'source_id' | 'slug'>, attempt: number): string {
  const h = digest(['extractor-facts-request-v1', hash, page.source_id, page.slug, attempt]);
  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-a${h.slice(17, 20)}-${h.slice(20, 32)}`;
}

/**
 * Hosts whose latest consumer since `writer_version_cutoff` is older than this
 * release: a pre-fix consumer there can expire restored facts again.
 */
async function mixedVersionWarnings(engine: BrainEngine): Promise<string[]> {
  const rows = await recentWriterVersions(engine, 30).catch(() => []);
  const latest = new Map<string, (typeof rows)[number]>();
  for (const row of rows.filter(r => r.role === 'consumer')) {
    const key = `${row.host_id}|${row.principal}`;
    const prior = latest.get(key);
    if (!prior || (row.last_seen ?? '') > (prior.last_seen ?? '')) latest.set(key, row);
  }
  const hosts = new Map<string, string>();
  for (const row of latest.values()) {
    const order = row.version === null ? -1 : compareWriterVersions(row.version, VERSION);
    if (order !== null && order >= 0) continue;
    const host = row.host_id ?? 'unknown (not recorded)';
    if (!hosts.has(host)) hosts.set(host, `${row.version_label}, last seen ${row.last_seen}`);
  }
  return [...hosts].map(([host, seen]) => `host ${host} still published writes with a consumer older than this release (${seen}); `
    + `a consumer older than v${EXTRACTOR_FACTS_FIX_VERSION} expires restored extractor facts again. Upgrade and restart gbrain on that host before applying.`);
}

async function hashParts(engine: BrainEngine, scope: RepairScope, includeAmbiguous: boolean, facts: ExtractorFactCandidate[]) {
  const 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]);
  return { kind: 'extractor-facts-v1', brain_id: scope.brain_id, sources, selection: { source_ids: scope.source_ids, include_ambiguous: includeAmbiguous }, facts };
}

function pageItem(page: ExtractorFactsPage, hash: string, index: number, last: boolean): PageItem {
  return { cursor: { phase: 0, id: index + 1 }, source_id: page.source_id, slug: page.slug, chars: 0,
    action: `restore ${page.facts.length} extractor fact(s)`, page, hash, last };
}

/** Pages of an approved set whose restore already finished (a committed request, or every fact active again). */
async function finishedPages(engine: BrainEngine, hash: string, pages: ExtractorFactsPage[]): Promise<Set<string>> {
  if (!pages.length) return new Set();
  const committed = await engine.executeRaw<{ source_id: string; slug: string }>(`SELECT DISTINCT source_id, slug FROM persistence_requests
    WHERE state='committed' AND operation='submit_job' AND source_id=ANY($1::text[]) AND slug=ANY($2::text[])
      AND (intent->>'preview_hash'=$3 OR request_id=ANY($4::uuid[]))`,
  [[...new Set(pages.map(p => p.source_id))], [...new Set(pages.map(p => p.slug))], hash, pages.map(p => p.request_id)]);
  const active = await engine.executeRaw<{ id: number | string }>(
    'SELECT id FROM facts WHERE id=ANY($1::bigint[]) AND expired_at IS NULL AND row_num IS NOT NULL', [pages.flatMap(p => p.facts.map(f => f.id))]);
  const restored = new Set(active.map(row => Number(row.id)));
  const done = new Set(committed.map(row => `${row.source_id}\u0000${row.slug}`));
  for (const page of pages) if (page.facts.every(f => restored.has(f.id))) done.add(`${page.source_id}\u0000${page.slug}`);
  return done;
}

export const extractorFactsRepair: RepairHandler = {
  kind: 'extractor-facts',
  embeds: false,
  async plan(engine, scope, after, opts): Promise<RepairPlan> {
    const includeAmbiguous = opts?.includeAmbiguous === true;
    if (!opts?.apply) {
      const managed = await managedPersistenceEnabled(engine);
      const facts = await classifyExtractorFacts(engine, scope.source_ids, { managed });
      const hash = previewHash(await hashParts(engine, scope, includeAmbiguous, facts));
      const pageIds = new Map((await engine.executeRaw<{ id: number | string; source_id: string; slug: string }>(
        'SELECT id, source_id, slug FROM pages WHERE source_id=ANY($1::text[]) AND slug=ANY($2::text[]) AND deleted_at IS NULL',
        [scope.source_ids, [...new Set(facts.map(f => f.slug))]])).map(row => [`${row.source_id}\u0000${row.slug}`, Number(row.id)]));
      const pages = new Map<string, ExtractorFactsPage>();
      for (const fact of facts) {
        if (fact.class === 'excluded' || fact.class === 'ambiguous' && !includeAmbiguous) continue;
        const key = `${fact.source_id}\u0000${fact.slug}`;
        const page = pages.get(key) ?? { source_id: fact.source_id, slug: fact.slug, page_id: pageIds.get(key)!,
          request_id: requestIdFor(hash, fact, 0), include_ambiguous: includeAmbiguous, scope: scope.source_ids, facts: [] };
        page.facts.push(fact);
        pages.set(key, page);
      }
      const approved = [...pages.values()];
      if (approved.length) await saveApprovedSet(engine, { command: 'extractor-facts', hash }, approved);
      const count = (klass: ExtractorFactClass) => facts.filter(f => f.class === klass).length;
      const listing: RepairListing[] = facts.map(fact => ({ item: `${fact.source_id}:${fact.slug}#${fact.id}`,
        class: fact.class === 'excluded' ? `excluded:${fact.reason}` : fact.class, detail: detail(fact) }));
      return { items: approved.map((page, index) => pageItem(page, hash, index, index === approved.length - 1)), preview_hash: hash,
        residuals: { evidenced: count('evidenced'), ambiguous: count('ambiguous'), excluded: count('excluded') },
        listing, warnings: await mixedVersionWarnings(engine) };
    }
    const command = await previewCommand(engine, scope, includeAmbiguous);
    if (!opts.expect) {
      throw new OperationError('invalid_params', 'gbrain repair extractor-facts --apply restores only the set a preview printed.',
        `Preview first: ${command} — then run the apply command it prints: ${command} --apply --expect <preview-hash>`,
        'docs/guides/repair.md#explicit-only-repair-kinds');
    }
    const approved = await loadApprovedSet<ExtractorFactsPage>(engine, { command: 'extractor-facts', hash: opts.expect, previewCommand: command,
      emptyHash: async () => previewHash(await hashParts(engine, scope, includeAmbiguous, [])) });
    const scopeKey = JSON.stringify(scope.source_ids);
    if (approved.items.some(page => page.include_ambiguous !== includeAmbiguous || JSON.stringify(page.scope) !== scopeKey)) {
      throw previewChangedError(opts.expect, command);
    }
    // Resume: skip pages the set's cursor (keyed by its approval hash in runRepair) already passed,
    // whatever their outcome, and pages whose restore already finished.
    const done = await finishedPages(engine, opts.expect, approved.items);
    const items = approved.items.map((page, index) => pageItem(page, opts.expect!, index, index === approved.items.length - 1))
      .filter(item => afterCursor(item.cursor, after) && !done.has(`${item.source_id}\u0000${item.slug}`));
    if (!items.length) await clearApprovedSet(engine, { command: 'extractor-facts', hash: opts.expect });
    return { items, preview_hash: opts.expect, residuals: { already_restored_pages: approved.items.length - items.length } };
  },
  async apply(ctx, entry): Promise<RepairItemOutcome> {
    const { page, hash, last } = entry as PageItem;
    const result = await managedPersistenceEnabled(ctx.engine)
      ? await restoreManaged(ctx.engine, ctx.config, page, hash, ctx.writeWaitMs)
      : await maintenanceTransaction(ctx.engine, async tx => {
        await tx.lockPageKeys([{ sourceId: page.source_id, slug: page.slug }]);
        return restorePageFacts(tx, page, false);
      });
    if (last) await clearApprovedSet(ctx.engine, { command: 'extractor-facts', hash });
    const changed = page.facts.length - result.restored.length;
    return { applied: result.restored.length > 0, outcome: !changed ? 'restored' : result.restored.length ? 'partially_restored' : 'changed_since_preview',
      ...(changed ? { reason: `${result.restored.length} of ${page.facts.length} restored; changed since the preview: ${result.changed.join(', ')}` } : {}) };
  },
};

interface RestoreResult { restored: number[]; changed: number[] }

async function restoreManaged(engine: BrainEngine, config: Parameters<typeof waitForWrite>[2], page: ExtractorFactsPage, hash: string,
  writeWaitMs: number | undefined): Promise<RestoreResult> {
  const unchanged: RestoreResult = { restored: [], changed: page.facts.map(f => f.id) };
  const authority = (await maintenancePreflight(engine, page.source_id))!;
  for (let attempt = 0; ; attempt++) {
    const requestId = attempt === 0 ? page.request_id : requestIdFor(hash, page, attempt);
    const prior = await getWriteRequest(engine, authority.writer.principal, requestId);
    if (prior && isTerminal(prior) && prior.state !== 'committed') continue;
    try {
      let receipt: Record<string, unknown>;
      if (prior) {
        await authorizeStoredRequest(engine, prior);
        // #6185: a pending restore replayed by a resumed apply waits like the apply's own writes.
        receipt = writeResponse(await waitForWrite(engine, prior, config, writeWaitMs));
      } else {
        const snapshot = await engine.readPageSnapshot(page.slug, { sourceId: page.source_id });
        if (!snapshot || snapshot.page.id !== page.page_id) return unchanged;
        receipt = await submitDatabaseMaintenanceIntent(engine, authority, page.slug,
          { kind: EXTRACTOR_FACTS_INTENT, expected_revision: snapshot.revision, preview_hash: hash, page }, requestId);
      }
      return { restored: (receipt.restored as number[] | undefined) ?? [], changed: (receipt.changed_since_preview as number[] | undefined) ?? [] };
    } catch (error) {
      if (error instanceof OperationError && ['revision_conflict', 'page_not_found', 'page_identity_changed'].includes(error.code)) return unchanged;
      throw error;
    }
  }
}

/**
 * Restores the page's approved facts that are still exactly as previewed,
 * under the page lock: each gets a fresh row number above every fact and
 * fence row of the page. Runs inside the managed publication or the unmanaged
 * transaction.
 */
async function restorePageFacts(tx: BrainEngine, page: ExtractorFactsPage, managed: boolean): Promise<RestoreResult> {
  const ids = page.facts.map(f => f.id);
  await tx.executeRaw('SELECT id FROM facts WHERE source_id=$1 AND id=ANY($2::bigint[]) FOR UPDATE', [page.source_id, ids]);
  const live = new Map((await classifyExtractorFacts(tx, [page.source_id], { managed, slug: page.slug })).map(f => [f.id, f]));
  const [live_page] = await tx.executeRaw<{ id: number | string; compiled_truth: string | null; max_row: number | string | null }>(
    `SELECT p.id, p.compiled_truth, (SELECT MAX(row_num) FROM facts WHERE source_id=$1 AND source_markdown_slug=$2) AS max_row
       FROM pages p WHERE p.source_id=$1 AND p.slug=$2 AND p.deleted_at IS NULL`, [page.source_id, page.slug]);
  // A page deleted and recreated at the same slug since the preview is another page.
  const snapshot = live_page && Number(live_page.id) === page.page_id ? live_page : undefined;
  const fenceRows = parseFactsFence(snapshot?.compiled_truth ?? '').facts.map(f => f.rowNum);
  let next = Math.max(Number(snapshot?.max_row ?? 0), ...fenceRows, 0) + 1;
  const result: RestoreResult = { restored: [], changed: [] };
  for (const approved of page.facts) {
    const current = live.get(approved.id);
    const same = !!snapshot && !!current && (['class', 'reason', 'expired_at', 'receipt', 'receipt_consumer', 'fact_hash'] as const)
      .every(field => current[field] === approved[field]);
    const updated = same ? await tx.executeRaw(`UPDATE facts SET expired_at=NULL, row_num=$3
      WHERE source_id=$1 AND id=$2 AND row_num IS NULL AND superseded_by IS NULL AND ${EXPIRY_TEXT('expired_at')}=$4 RETURNING id`,
    [page.source_id, approved.id, next, approved.expired_at]) : [];
    if (updated.length) { result.restored.push(approved.id); next++; } else result.changed.push(approved.id);
  }
  return result;
}

/**
 * Preparer for `managed_maintenance_restore_extractor_facts`: a database-only
 * publication on the page key that reclassifies and restores the approved
 * facts of one page, reporting the rest as `changed_since_preview`.
 */
export async function prepareExtractorFactsRestore(engine: BrainEngine, row: WriteRequest): Promise<PreparedMutation> {
  const intent = row.intent as { page?: ExtractorFactsPage; preview_hash?: unknown } | null;
  const page = intent?.page;
  if (!page || page.source_id !== row.source_id || page.slug !== row.slug || typeof intent?.preview_hash !== 'string' || !Array.isArray(page.facts)) {
    throw opError('invalid_params', 'The extractor facts restore intent does not name its page.',
      `Request ${row.request_id} for ${row.slug} in source ${row.source_id} does not name the page and preview it restores, so nothing changed. Preview the repair again and apply the new preview after the user approves.`,
      { fix: extractorPreviewFix(row.source_id) });
  }
  const snapshot = await engine.readPageSnapshot(row.slug, { sourceId: row.source_id });
  if (!snapshot || snapshot.page.id !== Number(row.page_id)) {
    throw opError('page_identity_changed', 'The conversation page was deleted or replaced before its facts were restored.',
      `Conversation page ${row.slug} in source ${row.source_id} was deleted or replaced after the preview, so request ${row.request_id} restored nothing. Preview the repair again; it reflects the current pages.`,
      { fix: extractorPreviewFix(row.source_id) });
  }
  await authorizeWrite(engine, row.authority, 'submit_job', row.slug);
  return { observedRevision: snapshot.revision, noop: true,
    validate: async tx => { await authorizeWrite(tx, row.authority, 'submit_job', row.slug); },
    apply: async tx => {
      const result = await restorePageFacts(tx, page, true);
      return { status: 'completed', preview_hash: intent!.preview_hash, restored: result.restored, changed_since_preview: result.changed };
    } };
}