Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
28.4 KB
Raw Blame
/**
 * `gbrain repair ghost-pages --source <id>` (#6696 B5): soft-delete live pages
 * whose canonical file is gone (a ghost: `liveFileDrift` reason
 * `canonical_file_missing` on the owner host, `src/core/ghost-pages.ts`).
 *
 * Explicit-only, preview-bound and destructive: the preview lists every ghost
 * with its recorded canonical path and revision, binds the set to the
 * canonical owner it ran under (host, worktree, owner epoch, source
 * incarnation) and saves it under its hash; `--apply --expect <hash> --yes`
 * (the user's consent, else exit 3 / `ask_user` with nothing changed)
 * soft-deletes exactly that set. Each page is a `delete_page` with
 * `allowMissingFile`: a managed brain submits one
 * `managed_maintenance_retire_ghost_page` request per page bound to its
 * revision, and the preparer re-runs the classifier and refuses when the file
 * exists again; filesystem publication refuses a file that appeared after
 * preparation (the prepared file target expects no bytes). An unmanaged brain
 * soft-deletes in one transaction after the same recheck. A page whose file
 * came back is skipped (`file_restored`) and the result asks for a new
 * preview; any other change is `changed_since_preview`.
 *
 * #6910: a ghost whose path is a member of the source's adopted shared skillpack (`skill_paths`, code
 * `ghost_skill_pack_member`, `src/core/ghost-pages.ts`) is listed apart with its restore step and never
 * approved: the pack's own file is missing and the shared skill publisher owns it. A legacy page on a
 * reserved path that is not a pack member is an ordinary ghost (the knowledge guard lets its retirement
 * through as a database-only soft delete). A page of the approved set that an item-level guard still refuses (a
 * registry `caller` refusal such as `skill_bundle_required`) is recorded `refused` with its code
 * and the apply continues; any other error (storage, contention, owner) still stops it.
 *
 * Refuses off the owner host (`not_owner_host`), fails closed when the source
 * root is unavailable or a check is ambiguous (`ghost_storage_unknown`),
 * never lists a declared db_only page, and applies the sync mass-delete valve
 * (`ghost_mass_delete_refused` unless `GBRAIN_ALLOW_MASS_RECONCILE=1`) when the
 * ghosts are more than half of a source's file-backed pages. Soft-deleted
 * pages are purged by the autopilot purge phase after 72 h; until then
 * `gbrain restore <slug> --force` undoes one page.
 */
import { existsSync } from 'node:fs';
import { join, relative, sep } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import type { PreparedMutation } from '../persistence/coordinator.ts';
import type { WriteRequest } from '../persistence/model.ts';
import { opError, OperationError, type OperationContext } from '../ops/contract.ts';
import { GHOST_RETIREMENT_INTENT } from '../shared-skills/knowledge-guard.ts';
import { readFix } from '../ops/op-fix.ts';
import { authorizeWrite } from '../persistence/authority.ts';
import { getWorktreeBinding, managedPersistenceEnabled } from '../persistence/ownership.ts';
import { maintenanceTransaction } from '../persistence/attribution.ts';
import { preparePageMutation } from '../persistence/page-prepare.ts';
import { nativeFileTarget } from '../persistence/native-file-target.ts';
import { clearDeletionHold, readSyncImportProvenance } from '../persistence/sync-holds.ts';
import { readRevisionAttestations } from '../persistence/sync-pass.ts';
import { readDeletionProvenance } from '../persistence/sync-origin-evidence.ts';
import { maintenancePreflight, submitMaintenanceIntent } from '../persistence/prepared-maintenance.ts';
import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
import { MASS_RECONCILE_MIN_PAGES, MASS_RECONCILE_RATIO, massReconcileAllowed } from '../sync-reconcile.ts';
import { ghostPageNow, scanGhostSource, UNRESOLVABLE_PATH_CODE, type GhostOwner, type GhostPage, type GhostSourceScan, type UnresolvablePage } from '../ghost-pages.ts';
import { afterCursor, REPAIR_ITEM_FAILURE_CODES, repairRequestId, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairPlan, type RepairScope } from './core.ts';

export const GHOST_PAGES_INTENT = GHOST_RETIREMENT_INTENT;
/** Ghosts one preview lists; a larger set is applied in rounds (preview, apply, preview again). */
export const GHOST_REPAIR_LIMIT = 1000;
export const GHOST_PURGE_FUSE_HOURS = 72;
const DOCS = 'docs/guides/repair.md#ghost-pages';
const FILE_CHANGED = 'The canonical file changed after preparation.';
/** Skill-path slugs a preview lists by name. */
const SKILL_PATH_SAMPLE = 20;
/** #6910: the stable code of a ghost on a file of the adopted shared skillpack. */
export const SKILL_PACK_MEMBER_CODE = 'ghost_skill_pack_member';
/** #6910: why such a ghost is left alone and the human step that clears it; the preview, `gbrain pages ghosts` and doctor say it. */
export const SKILL_PATH_NOTE = 'A ghost page whose path is a file of the source\'s adopted shared skillpack (skills/<name>/..., skillpack.json) is the pack\'s own file missing from the checkout; '
  + 'the shared skill publisher owns it, so this repair never removes the page. Restore the file on the owner host (git -C <source root> checkout -- <path> when it is committed; '
  + 'otherwise republish the skill with put_skill and its catalog expected_revision so the publisher writes it again); the page then stops being a ghost. These pages never block the other ghosts.';
/** #7736: why a page whose recorded path names no file inside its source is left alone; the preview, `gbrain pages ghosts` and doctor say it. */
export const UNRESOLVABLE_NOTE = 'A page whose recorded file path names no file inside its source (an absolute path, a path with .., or NUL) is never treated as a ghost or removed: '
  + 'gbrain cannot tell whether its file exists. Read it with gbrain pages status <slug> --source <id> --json; the page stays as it is.';
/** The `unresolvable` detail every reader prints. */
export const unresolvableDetail = (count: number, samples: UnresolvablePage[]) => ({ code: UNRESOLVABLE_PATH_CODE, count, samples, note: UNRESOLVABLE_NOTE, docs: DOCS });
/** The exact restore command for one pack-member ghost. */
export const skillPathRestore = (root: string | undefined, ghost: GhostPage) => `git -C ${root ?? '<source root>'} checkout -- ${ghost.path}`;
/** The `skill_paths` detail every reader prints. */
export function skillPathDetail(root: string | undefined, ghosts: GhostPage[], count = ghosts.length) {
  const sample = ghosts.slice(0, SKILL_PATH_SAMPLE);
  return { code: SKILL_PACK_MEMBER_CODE, count, slugs: sample.map(ghost => ghost.slug), owned_by: 'shared_skill_publisher',
    restore: sample.map(ghost => skillPathRestore(root, ghost)), note: SKILL_PATH_NOTE, docs: DOCS };
}

interface ApprovedGhost extends GhostPage { owner: GhostOwner; selection: string[] }
interface GhostItem extends RepairItem { ghost: GhostPage; owner: GhostOwner; hash: string; last: boolean }

export const ghostPreviewCommand = (sourceId: string) => `gbrain repair ghost-pages --source ${sourceId}`;
const previewFix = (sourceId: string) => readFix('Previews the ghost pages of the source again; writes nothing.',
  { argv: ['gbrain', 'repair', 'ghost-pages', '--source', sourceId, '--json'] });
const writerStatusFix = (sourceId: string) => readFix('Shows the source\'s canonical binding and owner host, read-only.',
  { argv: ['gbrain', 'sources', 'writer', 'status', '--source', sourceId, '--json'] });

/** The three consequences every preview and the consent payload state. */
export const GHOST_CONSEQUENCES = {
  purge: `Soft-deleted pages are purged for good by the autopilot purge phase ${GHOST_PURGE_FUSE_HOURS} h after deletion.`,
  undo: 'Until then, undo one page with gbrain restore <slug> --force (per slug; it writes the file back).',
  keep: 'To keep a page instead, restore its file at the recorded canonical path on the owner host (from Git or a backup; gbrain has no automated file restore), then run gbrain sync for the source.',
};

/** The consent payload of `--apply --expect <hash>` (registry `consentText`). */
export const GHOST_CONSENT_TEXT = {
  what: 'Soft-delete the previewed ghost pages: live pages whose canonical file is missing on the owner host',
  why: 'The preview listed each page with its recorded canonical path and revision; no sync can import a file that is not there, so every write to these pages refuses until the file is restored or the page is removed.',
  risk: `The pages leave search and reads now. ${GHOST_CONSEQUENCES.purge} ${GHOST_CONSEQUENCES.undo} ${GHOST_CONSEQUENCES.keep.replace('To keep a page instead, ', 'To keep a page instead, do not apply: ')} A page whose file comes back before the apply is kept.`,
  user_message: `Soft-delete the previewed ghost pages? They are purged after ${GHOST_PURGE_FUSE_HOURS} h; gbrain restore <slug> --force undoes one until then`,
};

/** The sync valve (#2828) over a source's file-backed pages. */
export function massGhosts(ghosts: number, fileBacked: number): boolean {
  return fileBacked > MASS_RECONCILE_MIN_PAGES && ghosts > fileBacked * MASS_RECONCILE_RATIO;
}

const sameOwner = (a: GhostOwner | undefined, b: GhostOwner) => !!a && a.host_id === b.host_id && a.worktree_id === b.worktree_id
  && a.owner_epoch === b.owner_epoch && a.source_incarnation === b.source_incarnation;

/** `not_owner_host`: the classifier only answers on the source's canonical owner host. */
export function notOwnerHostError(sourceId: string, reason: string): OperationError {
  return opError('not_owner_host', `Ghost pages of source ${sourceId} can only be checked and removed on its canonical owner host.`,
    reason === 'not_applicable'
      ? `Source ${sourceId} has no canonical checkout, so none of its pages owns a file that could be missing; nothing was listed or changed.`
      : `This host does not own source ${sourceId}'s active canonical worktree, so it cannot tell whether a page's file is missing; nothing was listed or changed. Run ${ghostPreviewCommand(sourceId)} in a terminal on the owner host (writer status names it).`,
    { reason, fix: writerStatusFix(sourceId), docs: DOCS });
}

export function ghostScanRefusal(scan: GhostSourceScan): OperationError | null {
  if (scan.status === 'known' || scan.reason === 'mirror_read_only') return null;
  if (scan.status === 'not_applicable') return notOwnerHostError(scan.source_id, scan.reason ?? 'not_owner_host');
  return opError('ghost_storage_unknown', `Ghost pages of source ${scan.source_id} cannot be classified: ${scan.reason === 'storage_unavailable'
    ? 'its canonical root is missing or is not a readable directory' : 'a canonical path could not be read or a page check was ambiguous'}.`,
  `Nothing was listed or changed: a page is never removed while its file may only be unreadable. Inspect the source's checkout on the owner host (writer status shows its root), fix it, then preview again: ${ghostPreviewCommand(scan.source_id)}`,
  { reason: scan.reason, fix: writerStatusFix(scan.source_id), docs: DOCS });
}

export function massRefusal(sourceId: string, ghosts: number, fileBacked: number): OperationError {
  return opError('ghost_mass_delete_refused', `Refusing to soft-delete ${ghosts} of ${fileBacked} file-backed page(s) of source ${sourceId} (more than ${Math.round(MASS_RECONCILE_RATIO * 100)}%).`,
    `That many missing files almost always means the checkout is the wrong path, unmounted or half-cloned, not that the files were deleted; nothing was changed. Check the checkout on the owner host first. If removing these pages is genuinely intended, ask the user, then rerun the same apply command with GBRAIN_ALLOW_MASS_RECONCILE=1.`,
    { fix: writerStatusFix(sourceId), docs: DOCS });
}

function hashParts(scope: RepairScope, owner: GhostOwner | undefined, ghosts: GhostPage[]) {
  return { kind: 'ghost-pages-v1', brain_id: scope.brain_id, selection: { source_ids: scope.source_ids }, owner: owner ?? null, ghosts };
}

function item(ghost: GhostPage, owner: GhostOwner, hash: string, last: boolean): GhostItem {
  return { cursor: { phase: 1, id: ghost.page_id }, source_id: ghost.source_id, slug: ghost.slug, chars: 0, action: 'soft_delete:canonical_file_missing',
    ghost, owner, hash, last };
}

export const ghostPagesRepair: RepairHandler = {
  kind: 'ghost-pages',
  embeds: false,
  async plan(engine, scope, after, opts): Promise<RepairPlan> {
    if (scope.source_ids.length !== 1) {
      throw opError('invalid_params', 'gbrain repair ghost-pages needs --source <id>.',
        'Ghost pages are checked on each source\'s own canonical owner host; name one source, e.g. gbrain repair ghost-pages --source default.',
        { fix: readFix('Lists the registered sources.', { argv: ['gbrain', 'sources', 'list', '--json'] }), docs: DOCS });
    }
    const sourceId = scope.source_ids[0]!;
    const command = ghostPreviewCommand(sourceId);
    const scan = await scanGhostSource(engine, sourceId, { candidateLimit: GHOST_REPAIR_LIMIT });
    const refusal = ghostScanRefusal(scan);
    if (refusal) throw refusal;
    const mass = massGhosts(scan.ghosts.length, scan.file_backed);
    if (!opts?.apply) {
      const skillPaths = scan.skill_paths.length;
      const ahead: GhostPage[] = [], ghosts: GhostPage[] = [];
      for (const ghost of scan.ghosts) (await ghostFileBacked(engine, ghost, scan.owner!) ? ghosts : ahead).push(ghost);
      const hash = previewHash(hashParts(scope, scan.owner, ghosts));
      if (ghosts.length) await saveApprovedSet<ApprovedGhost>(engine, { command: 'ghost-pages', hash },
        ghosts.map(ghost => ({ ...ghost, owner: scan.owner!, selection: scope.source_ids })));
      const warnings = [
        ...(mass ? [`${scan.ghosts.length} of ${scan.file_backed} file-backed page(s) are ghosts (more than ${Math.round(MASS_RECONCILE_RATIO * 100)}%): the apply refuses (ghost_mass_delete_refused) unless GBRAIN_ALLOW_MASS_RECONCILE=1; check the checkout first.`] : []),
        ...(scan.truncated ? [`More ghosts may exist past the first ${GHOST_REPAIR_LIMIT} checked; apply this set, then preview again.`] : []),
        ...(skillPaths ? [`${skillPaths} ghost page(s) on files of the shared skillpack are listed apart (${SKILL_PACK_MEMBER_CODE}) and not applied: ${SKILL_PATH_NOTE}`] : []),
        ...(scan.unresolvable_count ? [`${scan.unresolvable_count} page(s) record a file path that names no file inside the source; they are listed apart (${UNRESOLVABLE_PATH_CODE}) and not applied: ${UNRESOLVABLE_NOTE}`] : []),
        ...(ahead.length ? [`${ahead.length} ghost page(s) were written in the database after their file last held them, so each holds the only copy of that content; they are listed apart (${DATABASE_AHEAD_CODE}) and not applied.`] : []),
        ...(scan.reason === 'mirror_read_only' ? [`Source ${sourceId} is a read-only mirror: its pages publish no file, so none is a ghost.`] : []),
        ...(ghosts.length ? Object.values(GHOST_CONSEQUENCES) : []),
      ];
      return { warnings, items: ghosts.map((ghost, index) => item(ghost, scan.owner!, hash, index === ghosts.length - 1)), preview_hash: hash,
        residuals: { ghosts: ghosts.length, file_backed: scan.file_backed, inspected: scan.inspected, ...(skillPaths ? { skill_paths: skillPaths } : {}), ...(ahead.length ? { database_ahead: ahead.length } : {}),
          ...(scan.unresolvable_count ? { unresolvable: scan.unresolvable_count } : {}) },
        listing: [...ghosts.map(ghost => ({ item: `${ghost.source_id}:${ghost.slug}`, class: 'canonical_file_missing',
          detail: `file ${ghost.path} is missing; revision ${ghost.revision}` })),
        ...ahead.map(ghost => ({ item: `${ghost.source_id}:${ghost.slug}`, class: DATABASE_AHEAD_CODE, detail: databaseAheadDetail(ghost) })),
        ...scan.skill_paths.map(ghost => ({ item: `${ghost.source_id}:${ghost.slug}`, class: SKILL_PACK_MEMBER_CODE,
          detail: `shared skillpack file ${ghost.path} is missing; not applied. Restore it: ${skillPathRestore(scan.root, ghost)}` })),
        ...scan.unresolvable.map(page => ({ item: `${page.source_id}:${page.slug}`, class: UNRESOLVABLE_PATH_CODE,
          detail: `recorded path ${page.source_path} names no file inside the source; not applied` }))],
        details: { purge_fuse_hours: GHOST_PURGE_FUSE_HOURS, undo: 'gbrain restore <slug> --force', keep: GHOST_CONSEQUENCES.keep, mass_delete: mass, truncated: scan.truncated, docs: DOCS,
          ...(skillPaths ? { skill_paths: skillPathDetail(scan.root, scan.skill_paths) } : {}),
          ...(scan.unresolvable_count ? { unresolvable: unresolvableDetail(scan.unresolvable_count, scan.unresolvable) } : {}) } };
    }
    if (!opts.expect) {
      throw opError('invalid_params', 'gbrain repair ghost-pages --apply removes only the set a preview printed.',
        `Preview first: ${command} — then, after the user agrees, run the apply command it prints: ${command} --apply --expect <preview-hash> --yes`,
        { fix: previewFix(sourceId), docs: DOCS });
    }
    const approved = await loadApprovedSet<ApprovedGhost>(engine, { command: 'ghost-pages', hash: opts.expect, previewCommand: command,
      emptyHash: async () => previewHash(hashParts(scope, scan.owner, [])) });
    if (approved.items.some(ghost => JSON.stringify(ghost.selection) !== JSON.stringify(scope.source_ids) || !sameOwner(scan.owner, ghost.owner))) {
      throw previewChangedError(opts.expect, command);
    }
    if (massGhosts(approved.items.length, scan.file_backed) && !massReconcileAllowed()) throw massRefusal(sourceId, approved.items.length, scan.file_backed);
    const items = approved.items.map(({ selection: _selection, owner, ...ghost }, index) => item(ghost, owner, opts.expect!, index === approved.items.length - 1));
    return { items: items.filter(entry => afterCursor(entry.cursor, after)), preview_hash: opts.expect, residuals: {} };
  },
  async apply(ctx, entry): Promise<RepairItemOutcome> {
    const { ghost, owner, hash, last } = entry as GhostItem;
    let outcome: RepairItemOutcome;
    try {
      outcome = await retireGhost(ctx, ghost, owner, () => repairRequestId(ctx, 'ghost-pages', ghost, ghost.revision));
    } catch (error) {
      if (!(error instanceof OperationError) || !GHOST_ITEM_REFUSALS.has(error.code)) throw error;
      outcome = { applied: false, outcome: 'refused', reason: error.code, detail: { message: error.message } };
    }
    if (last) await clearApprovedSet(ctx.engine, { command: 'ghost-pages', hash });
    return outcome;
  },
  render(details) {
    return [`  each removed page: soft-deleted, purged after ${details.purge_fuse_hours} h; undo per slug: ${details.undo}; guide: ${details.docs}`];
  },
};

/** Refusals about one ghost only; a run-wide refusal (migrations_pending, worktree_dirty, writer transfer) stops the run and keeps the approval. */
const GHOST_ITEM_REFUSALS: ReadonlySet<string> = new Set([...REPAIR_ITEM_FAILURE_CODES, 'skill_bundle_required']);

const restored = (ghost: GhostPage): RepairItemOutcome => ({ applied: false, outcome: 'file_restored', detail: { path: ghost.path },
  reason: `The canonical file ${ghost.path} exists again, so ${ghost.slug} was kept; run ${ghostPreviewCommand(ghost.source_id)} again for a new preview.` });
const changed = (reason: string): RepairItemOutcome => ({ applied: false, outcome: 'changed_since_preview', reason });

/**
 * Whether a ghost's live revision is file-backed: the revision sync last imported from its file (the import record), or
 * one a committed sync write or a Git-published write produced (the attestation sync's own deletion proof reads). Any
 * other revision of a recorded page was written in the database after its file last held it, so the file's absence,
 * even a committed deletion, says nothing about that content and soft-deleting the page would drop the only copy of it.
 * A page with no import record is judged against the date of the commit that deleted its file, when one did.
 */
export async function ghostFileBacked(engine: BrainEngine, ghost: GhostPage, owner: GhostOwner): Promise<boolean> {
  const recorded = (await readSyncImportProvenance(engine, ghost.source_id, owner.source_incarnation, ghost.page_id))?.revision;
  if (recorded === ghost.revision) return true;
  const [page] = await engine.executeRaw<{ request_id: string | null; source_path: string | null; updated_ms: number }>(
    'SELECT revision_write_request_id::text AS request_id, source_path, (extract(epoch FROM updated_at) * 1000)::float8 AS updated_ms FROM pages WHERE id=$1 AND knowledge_revision::text=$2', [ghost.page_id, ghost.revision]);
  if (!page) return false;
  const [hit] = page.request_id ? await readRevisionAttestations(engine, ghost.source_id, owner.source_incarnation,
    [{ pageId: ghost.page_id, requestId: page.request_id, revision: ghost.revision, sourcePath: page.source_path ?? ghost.path }]) : [];
  if (hit && (hit.arm1 || hit.attested_hash !== null)) return true;
  if (recorded !== undefined) return false;
  // A page no import record covers (an older or unmanaged import) is ahead only when it was written after the commit that deleted its file.
  const binding = await getWorktreeBinding(engine, ghost.source_id, owner.host_id);
  if (!binding?.local_path) return true;
  const deletion = (await readDeletionProvenance(join(binding.local_path, binding.relative_path), [ghost.path])).get(ghost.path);
  return deletion?.kind !== 'deleted_by_commit' || Number(page.updated_ms) <= Date.parse(deletion.date);
}

export const DATABASE_AHEAD_CODE = 'database_ahead_of_file';
export const databaseAheadDetail = (ghost: GhostPage) => `file ${ghost.path} is gone, but page ${ghost.slug} was written in the database after the file last held it, so it holds the only copy of that content; not soft-deleted. Recreate the file from the page with gbrain repair file-drift --source ${ghost.source_id} --slug ${ghost.slug} --prefer database, or keep the page as it is`;

/** Whether the live page is still the approved ghost under the approved owner, with a file-backed revision; otherwise the outcome that skips it. */
async function stillApproved(engine: BrainEngine, ghost: GhostPage, owner: GhostOwner): Promise<RepairItemOutcome | null> {
  const now = await ghostPageNow(engine, ghost.source_id, ghost.slug);
  if (!now.ghost) return ['agrees', 'file_database_drift', 'recorded_file_present'].includes(now.reason) ? restored(ghost) : changed(`the page is no longer a ghost (${now.reason})`);
  if (!sameOwner(now.owner, owner)) return changed('the source\'s canonical owner changed since the preview');
  if (now.ghost.revision !== ghost.revision || now.ghost.page_id !== ghost.page_id || now.ghost.path !== ghost.path) return changed('the page or its recorded canonical path changed since the preview');
  if (!await ghostFileBacked(engine, ghost, owner)) return { applied: false, outcome: 'refused', reason: DATABASE_AHEAD_CODE, detail: { message: databaseAheadDetail(ghost) } };
  return null;
}

/** Soft-deletes one approved ghost; a managed brain submits it under `requestId()` (also `gbrain repair file-drift --prefer file` on a page whose file is gone, #6712 wave). */
export async function retireGhost(ctx: OperationContext, ghost: GhostPage, owner: GhostOwner, requestId: () => Promise<string>): Promise<RepairItemOutcome> {
  const engine = ctx.engine;
  const skip = await stillApproved(engine, ghost, owner);
  if (skip) return skip;
  if (await managedPersistenceEnabled(engine)) {
    const authority = (await maintenancePreflight(engine, ghost.source_id))!;
    try {
      await submitMaintenanceIntent(engine, authority, ghost.slug, { kind: GHOST_PAGES_INTENT, expected_revision: ghost.revision, ghost, owner }, await requestId());
    } catch (error) {
      if (error instanceof OperationError && ['revision_conflict', 'page_not_found', 'page_identity_changed'].includes(error.code)) return changed(error.message);
      if (error instanceof OperationError && error.code === 'source_changed') return restored(ghost);
      throw error;
    }
    return { applied: true, outcome: 'soft_deleted' };
  }
  const binding = await getWorktreeBinding(engine, ghost.source_id, owner.host_id);
  const file = binding?.local_path ? join(binding.local_path, binding.relative_path, ghost.path) : null;
  const result = await maintenanceTransaction(engine, async tx => {
    await tx.lockPageKeys([{ sourceId: ghost.source_id, slug: ghost.slug }]);
    const snapshot = await tx.readPageSnapshot(ghost.slug, { sourceId: ghost.source_id });
    if (!snapshot || snapshot.revision !== ghost.revision || Number(snapshot.page.id) !== ghost.page_id) return 'changed';
    if (!file || existsSync(file)) return 'restored';
    await tx.createVersion(ghost.slug, { sourceId: ghost.source_id });
    await tx.softDeletePage(ghost.slug, { sourceId: ghost.source_id });
    return 'deleted';
  });
  if (result === 'deleted') return { applied: true, outcome: 'soft_deleted' };
  return result === 'restored' ? restored(ghost) : changed('the page changed since the preview');
}

/**
 * Preparer for `managed_maintenance_retire_ghost_page`: re-runs the classifier under the approved owner, prepares a
 * `delete_page` with `allowMissingFile`, and refuses unless the prepared file target is the approved path with no
 * bytes (a file restored in between refuses here, or at filesystem publication when it appears later). #7736: a page
 * whose approved path is a recorded non-Markdown file is prepared at its slug path, which must hold no bytes either.
 * #7967: its file target is then moved to the recorded file, still expecting no bytes, so filesystem publication refuses
 * a recorded file restored after preparation and the door commits the recorded file's removal (on a git-canonical
 * source HEAD drops it with the page), never a removal of `<slug>.md`.
 */
export async function prepareGhostPageRetirement(engine: BrainEngine, row: WriteRequest, config: GBrainConfig): Promise<PreparedMutation> {
  const ghost = row.intent!.ghost as GhostPage | undefined;
  const owner = row.intent!.owner as GhostOwner | undefined;
  if (!ghost || !owner || ghost.slug !== row.slug || ghost.source_id !== row.source_id || ghost.page_id !== Number(row.page_id)) {
    throw opError('invalid_params', 'The ghost page retirement intent does not name its page.',
      `Request ${row.request_id} for ${row.slug} in source ${row.source_id} does not name the ghost page it removes, so nothing changed. Preview the repair again and apply the new preview after the user agrees.`,
      { fix: previewFix(row.source_id) });
  }
  const refuse = (outcome: RepairItemOutcome) => outcome.outcome === 'file_restored'
    ? opError('source_changed', FILE_CHANGED, `The canonical file ${ghost.path} of ${row.slug} in source ${row.source_id} exists again, so request ${row.request_id} removed nothing. Preview the repair again; a restored page is kept.`,
      { detail: 'ghost_file_restored', fix: previewFix(row.source_id) })
    : opError('revision_conflict', 'The ghost page changed since the preview.',
      `Page ${row.slug} in source ${row.source_id} changed after the preview (${outcome.reason}), so request ${row.request_id} removed nothing. Preview the repair again and apply the new preview after the user agrees.`,
      { fix: previewFix(row.source_id) });
  const skip = await stillApproved(engine, ghost, owner);
  if (skip) throw refuse(skip);
  await authorizeWrite(engine, row.authority, 'delete_page', row.slug);
  const page = await preparePageMutation(engine, { ...row, operation: 'delete_page' }, config, undefined, undefined, { allowMissingFile: true });
  const target = page.file ? relative(page.file.root, page.file.path).split(sep).join('/') : null;
  // #7736: a code or image page's write target is its slug path (prepareFileTarget resolves Markdown paths only), not the
  // recorded file the classifier just found missing again; that target must expect no bytes like any other.
  const recordedFile = !/\.mdx?$/i.test(ghost.path) && target === `${ghost.slug}.md`;
  if (!page.file || (target !== ghost.path && !recordedFile)) throw refuse(changed('its canonical file target moved'));
  if (page.file.expectedBeforeHash !== null) throw refuse(restored(ghost));
  const file = recordedFile ? { ...page.file, path: nativeFileTarget(page.file.root, join(page.file.root, ghost.path)) } : page.file;
  return { ...page, file, validate: async tx => { await page.validate?.(tx); await authorizeWrite(tx, row.authority, 'delete_page', row.slug); },
    // GBRA-133: the soft delete is the decision a held deletion of this file waited for, so its hold clears with it.
    apply: async (tx, preimage) => {
      const outcome = await page.apply(tx, preimage);
      return await clearDeletionHold(tx, { sourceId: row.source_id, incarnation: row.source_incarnation, path: ghost.path }) ? { ...outcome, hold_cleared: true } : outcome;
    } };
}