Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
37.3 KB
Raw Blame
/**
 * GBRA-161 PR 1a: `gbrain repair generations`, the preview-first undo and release path of the generation ledger. `--kind`
 * names the ledger kind and `--mode` the operation (default restore); one selector (`--run`, `--since`, `--key`,
 * `--generation`, or `--held` for release-held) bounds the set.
 *
 * - restore: republishes the item set the selected live generation replaced, as a new generation (`restore_of`): items it
 *   retired come back from their ledger preimages, items it overwrote return to their earlier content, and items it added
 *   are versioned and retired (`retired_by: generation-restore`). A key with an item edited since the generation, or one
 *   with no stored preimage, is refused whole and the apply exits incomplete; nothing of that key changes.
 * - release-held: publishes a held result once (shrunk, valve, attempts_exhausted; oversize after the operator raised
 *   `generations.max_items`). no_proof, fence_absent, tie and segmented_unsupported are refused: releasing them would
 *   manufacture the proof they lack.
 * - cleanup: lists what a managed source's activations left behind (GBRA-161 PR 1b): items an activated generation still
 *   waits on a member request for (resumed by the next extraction run) and orphan candidates (pages a `create` member
 *   wrote for an activation that never happened), each with its activation id. It is preview-only: an orphan is never
 *   retired automatically. A kind whose producer publishes in place (synthesis, GBRA-161 PR 4) also lists each earlier
 *   output a live generation left live because the re-synthesis did not match it (`unmatched_predecessor`, with why and
 *   what it still holds alone); `--apply --expect <hash> --yes` retires exactly the previewed ones (`retired_by:
 *   synthesis-cleanup`, versioned, restorable through the restore mode). Pending members and orphans stay list-only.
 *
 * Explicit-only, preview-bound, destructive consent: the preview saves the set under its hash and `--apply --expect <hash>
 * --yes` applies exactly that set, rechecking each key under its locks (`changed_since_preview` otherwise).
 */
import type { BrainEngine } from '../engine.ts';
import { opError, OperationError, type OperationContext } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { maintenanceTransaction } from '../persistence/attribution.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { assertInlineBody } from '../page-body/page-shape.ts';
import { digest, stableJson } from '../persistence/digest.ts';
import type { PreparedMutation } from '../persistence/coordinator.ts';
import type { WriteRequest } from '../persistence/model.ts';
import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
import { afterCursor, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairPlan, type RepairScope } from '../repair/core.ts';
import { generationAdapter, generationKinds } from './adapters/index.ts';
import { readGenerationsConfig, restoreDaysHint } from './config.ts';
import { RELEASABLE_HELD_REASONS, type GenerationAdapter, type GenerationKey, type HeldReason, type ProposedItem } from './contract.ts';
import { listOrphanCandidates, listPendingMembers, planManagedGeneration, requestUuid } from './managed.ts';
import { admitInPlaceGeneration } from './managed-retire.ts';
import { SYNTHESIS_CLEANUP_RETIRED_BY } from './adapters/synthesis.ts';
import { applyFenceRestore, planFenceRestore } from './fence-restore.ts';
import { activateGeneration, assertItemsLive, itemSetHash, lockGeneration, publishGeneration, readLiveGeneration, type LedgerItem } from './publish.ts';

export const GENERATION_MODES = ['restore', 'release-held', 'cleanup'] as const;
export type GenerationMode = typeof GENERATION_MODES[number];

/** What one run selects: the kind, the mode and the selectors the operator passed (`since` is a concrete ISO instant). */
export interface GenerationsSelection { kind: string; mode: GenerationMode; run?: string; since?: string; key?: string; generation?: number; held?: boolean }

/** The argv that selects this set again (preview, apply and consent replay share it). */
export function generationsSelectionArgv(selection: GenerationsSelection): string[] {
  return ['--kind', selection.kind, '--mode', selection.mode, ...(selection.run ? ['--run', selection.run] : []), ...(selection.key ? ['--key', selection.key] : []),
    ...(selection.generation !== undefined ? ['--generation', String(selection.generation)] : []), ...(selection.since ? ['--since', selection.since] : []),
    ...(selection.held ? ['--held'] : [])];
}

/** The read-only preview a notice prints for a kind (and optionally one key): the restore window, or the held set. */
export function generationsPreviewArgv(target: { kind: string; ownerKey?: string; sourceId?: string }, mode: GenerationMode = 'restore'): string[] {
  return ['gbrain', 'repair', 'generations', '--kind', target.kind, '--mode', mode, ...(target.sourceId ? ['--source', target.sourceId] : []),
    ...(target.ownerKey ? ['--key', target.ownerKey] : mode === 'release-held' ? ['--held'] : ['--since', `${restoreDaysHint()}d`]), '--json'];
}

const usage = (message: string, suggestion: string, selection: Partial<GenerationsSelection>) => opError('invalid_params', message, suggestion,
  { fix: readFix('Previews the generations repair; without --apply it writes nothing.', { argv: generationsPreviewArgv({ kind: selection.kind && generationAdapter(selection.kind) ? selection.kind : generationKinds()[0] ?? 'atom' },
    selection.mode === 'release-held' ? 'release-held' : 'restore') }) });

/** The usage refusal for an incomplete or contradictory selection, or null when it can run. */
export function generationsSelectionRefusal(selection: Partial<GenerationsSelection>): OperationError | null {
  const kinds = generationKinds().join(', ');
  const example = (mode: 'restore' | 'release-held' = 'restore') => generationsPreviewArgv({ kind: selection.kind && generationAdapter(selection.kind) ? selection.kind : generationKinds()[0] ?? 'atom' }, mode).slice(0, -1).join(' ');
  if (!selection.kind) return usage('gbrain repair generations needs --kind.', `Name the ledger kind (${kinds}), e.g. ${example()}.`, selection);
  if (!generationAdapter(selection.kind)) return usage(`--kind ${selection.kind} is not a generation kind this brain publishes (${kinds}).`, `Pass --kind ${generationKinds()[0] ?? 'atom'}.`, selection);
  if (!selection.mode || !GENERATION_MODES.includes(selection.mode)) {
    return usage(`--mode must be restore, release-held or cleanup (got "${selection.mode ?? ''}").`,
      'restore republishes the generation a key replaced; release-held publishes a held result once; cleanup lists pending members and orphan candidates.', selection);
  }
  if (!selection.run && !selection.since && !selection.key && selection.generation === undefined && !selection.held) {
    return usage('gbrain repair generations needs a selector: --run, --since, --key, --generation or --held.', `Bound the set, e.g. ${example(selection.mode === 'release-held' ? 'release-held' : 'restore')}.`, selection);
  }
  if (selection.held && selection.mode !== 'release-held') return usage('--held selects held results, which only --mode release-held publishes.', `Run ${example('release-held')}.`, selection);
  return null;
}

interface RestoreEntry {
  mode: 'restore'; id: number; source_id: string; owner_key: string; generation: number; restore_to: number; restore_to_id: number;
  revive: string[]; retire: string[]; refused: string[];
}
interface ReleaseEntry {
  mode: 'release-held'; id: number; source_id: string; owner_key: string; reason: HeldReason; hold_id: string; input_pin: string | null;
  attempts: number; proposal_bytes: number | null; items: number; refused: string[];
}
interface CleanupEntry {
  mode: 'cleanup'; id: number; source_id: string; owner_key: string; slug: string; activation_id: string;
  state: 'pending_overwrite' | 'retire_pending' | 'orphan_candidate' | 'unmatched_predecessor'; refused: string[];
  /** unmatched_predecessor: the live generation that left it, its identity at preview, why it was not matched and what it holds alone. */
  generation_id?: number; identity?: string; why?: string; missing?: { claims: number; quotes: number; citations: number } | null;
}
type Entry = RestoreEntry | ReleaseEntry | CleanupEntry;
interface EntryItem extends RepairItem { entry: Entry; hash: string; last: boolean; selection: GenerationsSelection }

function selectorSql(selection: GenerationsSelection, params: unknown[], alias: string): string {
  const parts: string[] = [];
  const add = (sql: string, value: unknown) => { params.push(value); parts.push(sql.replace('?', `$${params.length}`)); };
  if (selection.run) add(`${alias}.run_id = ?`, selection.run);
  if (selection.since) add(`${alias}.created_at >= ?::timestamptz`, selection.since);
  if (selection.key) add(`${alias}.owner_key = ?`, selection.key);
  if (selection.generation !== undefined) add(`${alias}.id = ?`, selection.generation);
  return parts.length ? ` AND ${parts.join(' AND ')}` : '';
}

const keyOf = (kind: string, sourceId: string, ownerKey: string): GenerationKey => ({ kind, sourceId, ownerKey });

/** What restoring the live generation `liveId` of `key` to its predecessor would do, read now. */
async function planRestore(db: BrainEngine, adapter: GenerationAdapter<unknown>, key: GenerationKey, liveId: number, prevId: number) {
  const items = await db.executeRaw<{ generation_id: number; item_key: string; identity_hash: string; action: string; preimage: Record<string, unknown> | null }>(
    'SELECT generation_id, item_key, identity_hash, action, preimage FROM derived_generation_items WHERE generation_id = ANY($1::bigint[])', [[liveId, prevId]]);
  const owned = (id: number) => new Map(items.filter(item => Number(item.generation_id) === id && item.action !== 'retired').map(item => [item.item_key, item.identity_hash]));
  const target = owned(prevId);
  const current = owned(liveId);
  const liveRecords = new Map(items.filter(item => Number(item.generation_id) === liveId).map(item => [item.item_key, item]));
  const rows = await adapter.readItems(db, key, [...new Set([...target.keys(), ...current.keys()])]);
  const revive: string[] = []; const retire: string[] = []; const refused: string[] = [];
  const preimages = new Map<string, Record<string, unknown>>();
  for (const [itemKey, identity] of target) {
    const row = rows.get(itemKey);
    if (row?.live && row.identityHash === identity) continue;
    const record = liveRecords.get(itemKey);
    const expectedNow = record?.action === 'retired' ? (row ? !row.live : false) : (row?.live === true && row.identityHash === record?.identity_hash);
    if (!record?.preimage || adapter.preimageIdentity(record.preimage) !== identity) { refused.push(`${itemKey}: no_preimage`); continue; }
    if (!expectedNow) { refused.push(`${itemKey}: edited_since`); continue; }
    revive.push(itemKey); preimages.set(itemKey, record.preimage);
  }
  for (const [itemKey, identity] of current) {
    if (target.has(itemKey)) continue;
    const row = rows.get(itemKey);
    if (!row?.live) continue;
    if (row.identityHash !== identity) refused.push(`${itemKey}: edited_since`);
    else retire.push(itemKey);
  }
  return { target, revive: revive.sort(), retire: retire.sort(), refused: refused.sort(), preimages, rows };
}

/** The earlier outputs live generations of an in-place kind left live unmatched, still live, unedited and still theirs. */
async function unmatchedPredecessors(db: BrainEngine, adapter: GenerationAdapter<unknown>, sources: string[], selection: GenerationsSelection) {
  const params: unknown[] = [sources, adapter.kind];
  const where = selectorSql(selection, params, 'g');
  const rows = await db.executeRaw<{ id: number; source_id: string; owner_key: string; activation_id: string | null; unmatched: Array<{ slug: string; why: string; missing: CleanupEntry['missing'] }> }>(
    `SELECT g.id, g.source_id, g.owner_key, g.activation_id, g.completeness->'unmatched' AS unmatched FROM derived_generations g
      WHERE g.source_id = ANY($1::text[]) AND g.kind = $2 AND g.state = 'live' AND jsonb_typeof(g.completeness->'unmatched') = 'array'${where} ORDER BY g.id`, params);
  const out: Array<Omit<CleanupEntry, 'mode' | 'id' | 'refused'>> = [];
  for (const row of rows) {
    const key = keyOf(adapter.kind, row.source_id, row.owner_key);
    const live = await readLiveGeneration(db, key);
    const items = await adapter.readItems(db, key, row.unmatched.map(entry => entry.slug));
    for (const entry of row.unmatched) {
      const item = items.get(entry.slug);
      if (!item?.live || live?.items.get(entry.slug) !== item.identityHash) continue;
      out.push({ source_id: row.source_id, owner_key: row.owner_key, slug: entry.slug, activation_id: row.activation_id ?? `generation:${row.id}`,
        state: 'unmatched_predecessor', generation_id: Number(row.id), identity: item.identityHash, why: entry.why, missing: entry.missing });
    }
  }
  return out;
}

async function selectEntries(db: BrainEngine, adapter: GenerationAdapter<unknown>, sources: string[], selection: GenerationsSelection, id?: number): Promise<Entry[]> {
  const params: unknown[] = [sources, adapter.kind];
  if (selection.mode === 'cleanup') {
    const since = selection.since ? Date.parse(selection.since) : null;
    const keyed = (row: { owner_key: string }) => !selection.key || row.owner_key === selection.key;
    const pending = (await listPendingMembers(db, sources, adapter.kind)).filter(keyed)
      .filter(row => selection.generation === undefined || row.generation_id === selection.generation);
    const orphans = selection.generation !== undefined ? [] : (await listOrphanCandidates(db, sources, adapter.kind)).filter(keyed)
      .filter(row => since === null || Date.parse(row.created_at) >= since);
    return [
      ...pending.map(row => ({ source_id: row.source_id, owner_key: row.owner_key, slug: row.slug, activation_id: row.activation_id,
        state: row.action === 'retire' ? 'retire_pending' as const : 'pending_overwrite' as const })),
      ...orphans.map(row => ({ source_id: row.source_id, owner_key: row.owner_key, slug: row.slug, activation_id: row.activation_id, state: 'orphan_candidate' as const })),
      ...(adapter.publishesInPlace ? await unmatchedPredecessors(db, adapter, sources, selection) : []),
    ].map((row, index) => ({ mode: 'cleanup' as const, id: index + 1, ...row, refused: [] }));
  }
  if (selection.mode === 'restore') {
    const where = id === undefined ? selectorSql(selection, params, 'g') : (params.push(id), ` AND g.id = $${params.length}`);
    const rows = await db.executeRaw<{ id: number; source_id: string; owner_key: string; generation: number; prev_id: number; prev_generation: number }>(
      `SELECT g.id, g.source_id, g.owner_key, g.generation, p.id AS prev_id, p.generation AS prev_generation
         FROM derived_generations g JOIN derived_generations p ON p.superseded_by = g.id AND p.state = 'superseded'
        WHERE g.source_id = ANY($1::text[]) AND g.kind = $2 AND g.state = 'live'${where} ORDER BY g.id`, params);
    const entries: Entry[] = [];
    for (const row of rows) {
      const key = keyOf(adapter.kind, row.source_id, row.owner_key);
      const plan = adapter.fence ? await planFenceRestore(db, key, Number(row.id), Number(row.prev_id)) : await planRestore(db, adapter, key, Number(row.id), Number(row.prev_id));
      if (!plan.revive.length && !plan.retire.length && !plan.refused.length) continue;
      entries.push({ mode: 'restore', id: Number(row.id), source_id: row.source_id, owner_key: row.owner_key, generation: Number(row.generation),
        restore_to: Number(row.prev_generation), restore_to_id: Number(row.prev_id), revive: plan.revive, retire: plan.retire, refused: plan.refused });
    }
    return entries;
  }
  const where = id === undefined ? selectorSql(selection, params, 'g') : (params.push(id), ` AND g.id = $${params.length}`);
  const config = await readGenerationsConfig(db);
  const rows = await db.executeRaw<{ id: number; source_id: string; owner_key: string; held_reason: HeldReason; hold_id: string; input_pin: string | null;
    attempts: number; proposal_bytes: number | null; items: number | null }>(
    `SELECT g.id, g.source_id, g.owner_key, g.held_reason, g.hold_id, g.input_pin, g.attempts, g.proposal_bytes, jsonb_array_length(g.proposal) AS items
       FROM derived_generations g WHERE g.source_id = ANY($1::text[]) AND g.kind = $2 AND g.state = 'held'${where} ORDER BY g.id`, params);
  return rows.map(row => {
    const refused = !RELEASABLE_HELD_REASONS.has(row.held_reason) ? [`${row.owner_key}: ${row.held_reason} is not releasable`]
      : row.items === null ? [`${row.owner_key}: no retained proposal`]
      : row.held_reason === 'oversize' && Number(row.items) > config.maxItems ? [`${row.owner_key}: oversize until generations.max_items is raised`] : [];
    return { mode: 'release-held' as const, id: Number(row.id), source_id: row.source_id, owner_key: row.owner_key, reason: row.held_reason, hold_id: row.hold_id,
      input_pin: row.input_pin, attempts: Number(row.attempts), proposal_bytes: row.proposal_bytes === null ? null : Number(row.proposal_bytes), items: Number(row.items ?? 0), refused };
  });
}

function describeEntry(entry: Entry): string {
  const refused = entry.refused.length ? `; refused: ${entry.refused.join(', ')}` : '';
  if (entry.mode === 'cleanup' && entry.state === 'unmatched_predecessor') {
    const missing = entry.missing ? `; holds alone ${entry.missing.claims} claim(s), ${entry.missing.quotes} quote(s), ${entry.missing.citations} citation(s)` : '';
    return `unmatched predecessor ${entry.slug} (generation ${entry.generation_id}, ${entry.why === 'no_subject' ? 'no successor on the same subject' : entry.why === 'unreadable' ? 'its body was not compared (segmented)' : 'the successor does not cover it'}${missing}), live until you retire it`;
  }
  if (entry.mode === 'cleanup') return `${entry.state.replace('_', ' ')} ${entry.slug} (activation ${entry.activation_id})${entry.state === 'orphan_candidate' ? ', never retired automatically' : ', resumed by the next extraction run'}`;
  if (entry.mode === 'release-held') return `held ${entry.reason}, ${entry.items} item(s), ${entry.attempts} attempt(s)${refused}`;
  return `generation ${entry.generation} back to ${entry.restore_to}: revive ${entry.revive.length}, retire ${entry.retire.length}${refused}`;
}

async function hashParts(engine: BrainEngine, scope: RepairScope, selection: GenerationsSelection, entries: Entry[]) {
  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: 'generations-v1', brain_id: scope.brain_id, sources, selection, entries };
}

function previewCommand(scope: RepairScope, selection: GenerationsSelection): string {
  return ['gbrain', 'repair', 'generations', ...(scope.source_ids.length === 1 ? ['--source', scope.source_ids[0]!] : []), ...generationsSelectionArgv(selection)].join(' ');
}

function requireAdapter(selection: GenerationsSelection | undefined): { adapter: GenerationAdapter<unknown>; selection: GenerationsSelection } {
  const refusal = generationsSelectionRefusal(selection ?? {});
  if (refusal) throw refusal;
  return { adapter: generationAdapter(selection!.kind)!, selection: selection! };
}

type Approved = Entry & { selection: GenerationsSelection; sources: string[] };

export const generationsRepair: RepairHandler = {
  kind: 'generations',
  publication: 'projection',
  embeds: true,
  outcomeItemsLimit: 1000,
  async plan(engine, scope, after, opts): Promise<RepairPlan> {
    const { adapter, selection } = requireAdapter(opts?.generations);
    const command = previewCommand(scope, selection);
    const item = (entry: Entry, hash: string, last: boolean): EntryItem => ({ cursor: { phase: entry.mode === 'restore' ? 1 : entry.mode === 'release-held' ? 2 : 3, id: entry.id },
      source_id: entry.source_id, slug: entry.mode === 'cleanup' ? entry.slug : entry.owner_key, chars: 0, action: entry.mode === 'restore' ? 'restore' : entry.mode === 'release-held' ? 'release' : 'list',
      entry, hash, last, selection });
    if (!opts?.apply) {
      const entries = await selectEntries(engine, adapter, scope.source_ids, selection);
      const hash = previewHash(await hashParts(engine, scope, selection, entries));
      if (entries.length) await saveApprovedSet<Approved>(engine, { command: 'generations', hash }, entries.map(entry => ({ ...entry, selection, sources: scope.source_ids })));
      return { items: entries.map((entry, index) => item(entry, hash, index === entries.length - 1)), preview_hash: hash,
        residuals: { keys: entries.length, refused: entries.filter(entry => entry.refused.length).length },
        listing: entries.map(entry => ({ item: `${entry.source_id}:${entry.mode === 'cleanup' ? entry.slug : entry.owner_key}`,
          class: entry.mode === 'cleanup' ? entry.state : entry.refused.length ? 'refused' : entry.mode, detail: describeEntry(entry) })) };
    }
    if (selection.mode === 'cleanup' && !adapter.publishesInPlace) {
      throw new OperationError('invalid_params', `gbrain repair generations --mode cleanup only lists pending members and orphan candidates for --kind ${selection.kind}; there is nothing to apply.`,
        `Pending members resume on the next extraction run of their source. An orphan candidate is never retired automatically: show the user ${command} and delete one only if they decide to.`,
        'docs/guides/repair.md#generations');
    }
    if (!opts.expect) {
      throw new OperationError('invalid_params', 'gbrain repair generations --apply applies only the set a preview printed.',
        `Preview first: ${command} — then run the apply command it prints: ${command} --apply --expect <preview-hash> --yes`, 'docs/guides/repair.md#generations');
    }
    const approved = await loadApprovedSet<Approved>(engine, { command: 'generations', hash: opts.expect, previewCommand: command,
      emptyHash: async () => previewHash(await hashParts(engine, scope, selection, [])) });
    if (approved.items.some(entry => stableJson(entry.selection) !== stableJson(selection) || stableJson(entry.sources) !== stableJson(scope.source_ids))) {
      throw previewChangedError(opts.expect, command);
    }
    const items = approved.items.map(({ selection: _s, sources: _src, ...entry }, index) => item(entry, opts.expect!, index === approved.items.length - 1));
    return { items: items.filter(entry => afterCursor(entry.cursor, after)), preview_hash: opts.expect, residuals: {} };
  },
  async apply(ctx, raw): Promise<RepairItemOutcome> {
    const { entry, hash, last, selection } = raw as EntryItem;
    const adapter = generationAdapter(selection.kind)!;
    const outcome = await applyEntry(ctx, adapter, entry, selection);
    if (last) await clearApprovedSet(ctx.engine, { command: 'generations', hash });
    return outcome;
  },
  async report(_ctx, _scope, result, opts) {
    const refused = (result.outcome_items ?? []).filter(item => item.outcome === 'refused');
    if (result.mode !== 'apply' || !refused.length || !opts.generations) return {};
    return { stopped: { reason: 'incomplete', message: `${refused.length} key(s) were refused and left unchanged: ${refused.map(item => item.reason).join('; ')}`,
      fix: readFix('Previews the generations repair again, read-only.', { argv: ['gbrain', 'repair', 'generations', ...generationsSelectionArgv(opts.generations), '--json'] }) } };
  },
};

async function applyEntry(ctx: OperationContext, adapter: GenerationAdapter<unknown>, approved: Entry, selection: GenerationsSelection): Promise<RepairItemOutcome> {
  const changed = (reason: string): RepairItemOutcome => ({ applied: false, outcome: 'changed_since_preview', reason });
  if (approved.mode === 'cleanup' && approved.state === 'unmatched_predecessor') return retireUnmatched(ctx.engine, adapter, approved);
  if (approved.mode === 'cleanup') return { applied: false, outcome: 'listed', reason: `${approved.slug}: ${approved.state.replace('_', ' ')} entries are listed, never applied` };
  if (approved.refused.length) return { applied: false, outcome: 'refused', reason: approved.refused.join(', ') };
  const key = keyOf(adapter.kind, approved.source_id, approved.owner_key);
  if (approved.mode === 'release-held') {
    const [row] = await ctx.engine.executeRaw<{ proposal: ProposedItem[] | null; hold_id: string }>(
      `SELECT proposal, hold_id FROM derived_generations WHERE id=$1 AND state='held'`, [approved.id]);
    if (!row || row.hold_id !== approved.hold_id || !row.proposal) return changed('the held result changed or was released since the preview');
    if (await managedPersistenceEnabled(ctx.engine)) return releaseManaged(ctx.engine, adapter, key, approved, row.proposal);
    const outcome = await publishGeneration(ctx.engine, adapter, { key, items: row.proposal, runId: `release:${approved.hold_id}`, release: { holdId: approved.hold_id, reason: approved.reason } });
    if (outcome.state === 'held') return { applied: false, outcome: 'refused', reason: `${approved.owner_key}: still held (${outcome.reason})` };
    return { applied: true, outcome: 'released', detail: { generation: outcome.generation, ...(outcome.state === 'published' ? { retired: outcome.retired.length } : {}) } };
  }
  if (adapter.fence) {
    const restored = await applyFenceRestore(ctx, key, approved);
    if (restored === 'changed') return changed('the live generation, its fence or the page changed since the preview');
    if (Array.isArray(restored)) return { applied: false, outcome: 'refused', reason: restored.join(', ') };
    return { applied: true, outcome: 'restored', detail: { restore_of: approved.restore_to, revived: approved.revive.length, retired: approved.retire.length } };
  }
  let restored: Awaited<ReturnType<typeof restoreGeneration>>;
  if (await managedPersistenceEnabled(ctx.engine)) {
    if (!adapter.databaseOnly) {
      return { applied: false, outcome: 'refused', reason: `${approved.owner_key}: a managed source restores retired atoms with gbrain repair atoms-restore; a generation restore here runs on unmanaged brains only` };
    }
    restored = await submitManagedRestore(ctx.engine, adapter, key, approved);
  } else {
    restored = await maintenanceTransaction(ctx.engine, tx => restoreGeneration(tx, adapter, key, approved));
  }
  if (restored === 'changed') return changed('the live generation or its items changed since the preview');
  if (Array.isArray(restored)) return { applied: false, outcome: 'refused', reason: restored.join(', ') };
  const fileHolds = adapter.publishesInPlace ? await restoreInPlaceFiles(ctx.engine, key.sourceId, approved.revive, approved.retire) : [];
  return { applied: true, outcome: 'restored', detail: { generation: restored.generation, restore_of: approved.restore_to, revived: approved.revive.length, retired: approved.retire.length,
    ...(fileHolds.length ? { file_holds: fileHolds } : {}) } };
}

/**
 * GBRA-161 PR 4: the operator's retirement of one previewed unmatched predecessor, as an approved retirement of its key
 * (versioned, `retired_by: synthesis-cleanup`, bound to the identity the preview showed). Unmanaged: one transaction, its
 * file removed after when the database holds everything in it; managed: one activation and its retire member through the writer.
 */
async function retireUnmatched(engine: BrainEngine, adapter: GenerationAdapter<unknown>, approved: CleanupEntry): Promise<RepairItemOutcome> {
  const key = keyOf(adapter.kind, approved.source_id, approved.owner_key);
  const changed = (why: string): RepairItemOutcome => ({ applied: false, outcome: 'changed_since_preview', reason: `${approved.slug}: ${why}` });
  const live = await readLiveGeneration(engine, key);
  if (!approved.identity || live?.items.get(approved.slug) !== approved.identity) return changed('the page or its generation changed since the preview');
  const request = { key, items: [], runId: `cleanup:${approved.generation_id}:${approved.slug}`,
    approved: { retire: [approved.slug], retiredBy: SYNTHESIS_CLEANUP_RETIRED_BY, expect: { [approved.slug]: approved.identity } } };
  if (await managedPersistenceEnabled(engine)) {
    const { maintenancePreflight } = await import('../persistence/prepared-maintenance.ts');
    const authority = await maintenancePreflight(engine, key.sourceId);
    if (!authority) return { applied: false, outcome: 'refused', reason: `${approved.slug}: the source is no longer managed; preview again` };
    const plan = await planManagedGeneration(engine, adapter, request, { retiredBy: SYNTHESIS_CLEANUP_RETIRED_BY });
    if (plan.kind !== 'publish') return changed(plan.kind === 'held' ? `held (${plan.outcome.reason})` : 'nothing left to retire');
    await admitInPlaceGeneration(engine, authority, plan);
    return { applied: true, outcome: 'retired', detail: { retired_by: SYNTHESIS_CLEANUP_RETIRED_BY } };
  }
  const outcome = await publishGeneration(engine, adapter, request);
  if (outcome.state === 'held') return { applied: false, outcome: 'refused', reason: `${approved.slug}: held (${outcome.reason})` };
  if (outcome.state !== 'published' || !outcome.retired.includes(approved.slug)) return changed('the page changed since the preview');
  const { removeDreamPageFile } = await import('../cycle/derived-write-through.ts');
  const file = await removeDreamPageFile(engine, '', approved.slug, key.sourceId, '');
  return { applied: true, outcome: 'retired', detail: { generation: outcome.generation, retired_by: SYNTHESIS_CLEANUP_RETIRED_BY, ...(file.held ? { file_held: file.held } : {}) } };
}

/**
 * GBRA-161 PR 4: the files of an in-place kind (synthesis pages) after its unmanaged restore committed: each revived page is
 * written back to its file and each retired page's file removed, both only where the file holds nothing the database
 * lacks (otherwise its `file_database_drift` entry is returned and the file stays).
 */
async function restoreInPlaceFiles(engine: BrainEngine, sourceId: string, revived: readonly string[], retired: readonly string[]): Promise<string[]> {
  const { removeDreamPageFile, reverseWriteDreamRefs } = await import('../cycle/derived-write-through.ts');
  const { renderPageToMarkdown } = await import('../cycle/synthesize.ts');
  const held: string[] = [];
  for (const slug of retired) { const file = await removeDreamPageFile(engine, '', slug, sourceId, ''); if (file.held) held.push(file.held); }
  await reverseWriteDreamRefs(engine, '', revived.map(slug => ({ slug, source_id: sourceId })), { phase: 'repair generations', nativeSourceId: '', render: renderPageToMarkdown, held });
  return held;
}

/** The approved restore of one key, under its locks in the caller's transaction: 'changed', the refused keys, or the new generation. */
async function restoreGeneration(tx: BrainEngine, adapter: GenerationAdapter<unknown>, key: GenerationKey, approved: RestoreEntry): Promise<'changed' | string[] | { generation: number }> {
  const live = await readLiveGeneration(tx, key);
  const plan0 = live?.id === approved.id ? await planRestore(tx, adapter, key, approved.id, approved.restore_to_id) : null;
  await lockGeneration(tx, adapter, key, plan0 ? [...plan0.target.keys(), ...plan0.retire] : []);
  if (!plan0 || (await readLiveGeneration(tx, key))?.id !== approved.id) return 'changed' as const;
  const plan = await planRestore(tx, adapter, key, approved.id, approved.restore_to_id);
  if (stableJson([plan.revive, plan.retire, plan.refused]) !== stableJson([approved.revive, approved.retire, approved.refused])) return 'changed' as const;
  if (plan.refused.length) return plan.refused;
  for (const itemKey of plan.revive) await adapter.restoreItem(tx, key, itemKey, plan.preimages.get(itemKey)!);
  await adapter.retireItems(tx, key, plan.retire, 'generation-restore');
  await assertItemsLive(tx, adapter, key, plan.target);
  const items: LedgerItem[] = [
    ...[...plan.target].map(([itemKey, identity]) => ({ key: itemKey, identityHash: identity, action: plan.revive.includes(itemKey) ? 'revived' as const : 'kept' as const,
      ...(plan.revive.includes(itemKey) && plan.rows.get(itemKey)?.live ? { preimage: plan.rows.get(itemKey)!.preimage() } : {}) })),
    ...plan.retire.map(itemKey => ({ key: itemKey, identityHash: plan.rows.get(itemKey)!.identityHash, action: 'retired' as const, preimage: plan.rows.get(itemKey)!.preimage() })),
  ];
  const setHash = itemSetHash([...plan.target].map(([itemKey, identityHash]) => ({ key: itemKey, identityHash })));
  const activated = await activateGeneration(tx, key, live, { operationId: `restore:${approved.id}:${approved.restore_to_id}`, input: await adapter.readInput(tx, key, undefined),
    setHash, completeness: { complete: true, restore: approved.restore_to }, restoreOf: approved.restore_to_id }, items);
  return { generation: activated.generation };
}

export const GENERATION_RESTORE_INTENT = 'managed_generation_restore';

/**
 * GBRA-161 PR 3: a managed source restores a database-only kind (chronicle events) in one coordinated request, journaled
 * on the key's input page and bound to its current revision: the request runs `restoreGeneration` under the item locks.
 */
async function submitManagedRestore(engine: BrainEngine, adapter: GenerationAdapter<unknown>, key: GenerationKey, approved: RestoreEntry): Promise<'changed' | string[] | { generation: number }> {
  const { maintenancePreflight, submitDatabaseMaintenanceIntent } = await import('../persistence/prepared-maintenance.ts');
  const authority = await maintenancePreflight(engine, key.sourceId);
  if (!authority) return [`${approved.owner_key}: the source is no longer managed; preview again`];
  const slug = adapter.lockKeys(key, [])[0]!.slug;
  const input = await engine.readPageSnapshot(slug, { sourceId: key.sourceId, includeDeleted: true });
  const intent = { kind: GENERATION_RESTORE_INTENT, key, approved, expected_revision: input?.revision ?? null, ...(input?.page.deleted_at ? { deleted_page: true } : {}) };
  const receipt = await submitDatabaseMaintenanceIntent(engine, authority, slug, intent, requestUuid(digest(['generation-restore-v1', key, approved.id, approved.restore_to_id, input?.revision ?? null])));
  const result = receipt.restore as 'changed' | string[] | { generation: number } | undefined;
  return result ?? 'changed';
}

/** Preparer of `managed_generation_restore` (trusted local only): the restore of a database-only kind, writing no file. */
export async function prepareGenerationRestore(engine: BrainEngine, row: WriteRequest): Promise<PreparedMutation> {
  const p = row.intent as { kind?: string; key?: GenerationKey; approved?: RestoreEntry; expected_revision?: string | null } | null;
  const adapter = p?.key ? generationAdapter(p.key.kind) : undefined;
  if (!p || p.kind !== GENERATION_RESTORE_INTENT || row.authority.remote || !adapter?.databaseOnly || !p.approved || p.key!.sourceId !== row.source_id) {
    throw opError('permission_denied', 'Unsupported generation restore request.',
      `Request ${row.request_id} in source ${row.source_id} is not a generation restore the trusted local writer admitted, so the coordinator refused it before any change. Restores run only from gbrain repair generations on the brain host.`);
  }
  const key = p.key!;
  const approved = p.approved;
  return { observedRevision: p.expected_revision ?? null, noop: true, additionalPageKeys: adapter.lockKeys(key, [...approved.revive, ...approved.retire]),
    apply: async tx => ({ restore: await restoreGeneration(tx, adapter, key, approved) }) };
}

/**
 * GBRA-161 PR 1b: a managed source publishes a released held result through its writer (generations/managed.ts): the
 * retained proposal is admitted as one activation batch against the origin's current input. Atom page keys only; a
 * transcript key's held result clears when its next extraction lands on a different result.
 */
async function releaseManaged(engine: BrainEngine, adapter: GenerationAdapter<unknown>, key: GenerationKey, approved: ReleaseEntry, proposal: ProposedItem[]): Promise<RepairItemOutcome> {
  const refused = (reason: string): RepairItemOutcome => ({ applied: false, outcome: 'refused', reason: `${approved.owner_key}: ${reason}` });
  if (adapter.kind !== 'atom' || !key.ownerKey.startsWith('source_slug:')) return refused('a managed release publishes atom page keys only');
  const atoms = await import('../persistence/atom-maintenance.ts');
  const session = await atoms.managedAtomSession(engine, key.sourceId);
  if (!session) return refused('the source is no longer managed; preview again');
  const slug = key.ownerKey.slice('source_slug:'.length);
  const page = await engine.getPage(slug, { sourceId: key.sourceId });
  if (!page?.content_hash) return refused(`origin page ${slug} is gone; the held result cannot publish`);
  assertInlineBody(page, 'repair generations release-held');
  const origin = await atoms.readAtomOrigin(engine, session, { kind: 'page', slug, content: page.compiled_truth, contentHash: page.content_hash });
  const outcome = await atoms.publishManagedAtomGeneration(engine, session, origin, proposal.map(item => ({ slug: item.key, content: item.content, links: [] })),
    { key, content: page.compiled_truth, runId: `release:${approved.hold_id}`, release: { holdId: approved.hold_id, reason: approved.reason } });
  if (outcome.state === 'held') return refused(`still held (${outcome.reason})`);
  const failed = outcome.receipts.filter(receipt => receipt.state !== 'committed');
  if (failed.length) return refused(`${failed.length} request(s) of the release did not commit (${failed.map(receipt => receipt.request_id).join(', ')})`);
  return { applied: true, outcome: 'released', detail: { requests: outcome.receipts.length } };
}