Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
29.3 KB
Raw Blame
/**
 * #5988 legacy (unmanaged) sync holds. A file whose content gbrain refuses
 * deterministically (unreadable or ambiguous frontmatter, a frontmatter slug
 * naming another page, over-size, an operator content reject) is held in the
 * shared Git hold store instead of failing the run: it stays out of
 * `failedFiles` and the #1939 auto-skip streak, never gates the bookmark, and
 * is re-screened on later runs until it imports, is deleted, or a newer gbrain
 * can read it. `sync.holds=fail` keeps today's fail-closed behavior, and
 * company-brain sources never hold (their approved manifest keeps blocking).
 */
import { createHash, randomUUID } from 'crypto';
import { importFenceTally } from '../../core/fence-repair/report.ts';
import { recordSyncRunTrend } from '../../core/fence-repair/census-store.ts';
import { existsSync, lstatSync } from 'fs';
import { join } from 'path';
import type { SyncResult } from '../sync.ts';
import type { BrainEngine } from '../../core/engine.ts';
import { serr } from '../../core/console-prefix.ts';
import { currentCompanyBrainSync } from '../../core/company-brain/profile.ts';
import { RECOVERY_VERSION } from '../../core/frontmatter-recovery.ts';
import { importSizeLimit, contentRefusalFromReceipt, isContentRefusal, type ContentRefusal } from '../../core/import-screen.ts';
import { slugConflictHoldMessage, type ImportResult } from '../../core/import-file.ts';
import { classifyImportHold, parseMarkdown } from '../../core/markdown.ts';
import { noncanonicalPrivateHold } from '../../core/persistence/visibility-request.ts';
import { readSourceFileSync } from '../../core/minions/source-filesystem.ts';
import { maintenanceBeliefTransaction } from '../../core/belief/writers.ts';
import type { SyncRename } from '../../core/persistence/sync-discovery.ts';
import {
  addRecovered, buildHoldReport, clearGitHold, clearGitHoldRetryPaths, gitHoldItem, holdRescreenDue, readGitHoldRetryPaths, readGitSourceHolds,
  readSyncHoldPolicy, recoveredReport, writeGitHold, type GitHoldCode, type GitHoldItem, type GitHoldRecord, type GitHoldReason, type SyncHoldPolicy,
} from '../../core/persistence/sync-holds.ts';
import { DEFAULT_SOURCE_ID, hasMalformedPathSegment, isCodeFilePath, resolveSlugForPath, sanitizePathForDisplay, slugifyPath } from '../../core/sync.ts';
import type { SyncActivePack } from './sync-run.ts';
import { isPathContained } from '../../core/path-confine.ts';
import { bytePathHoldGone } from '../../core/sync-byte-paths.ts';
import { bindOrigin } from '../../core/persistence/origin-guard.ts';
import { CLASSIC_FILE_HOLD_CODES, classifyClassicFile, type ClassicFileHold } from '../../core/classic-file-holds.ts';

/** The file at a repo-relative path from git or a hold row, or null when it is missing or resolves outside the source root. */
function fileUnderRoot(root: string, path: string): string | null {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- path is a repo-relative path from git or a hold row; isPathContained realpaths both sides and rejects anything outside root
  const filePath = join(root, path);
  return isPathContained(filePath, root) ? filePath : null;
}

export interface LegacyHolds {
  readonly sourceId: string;
  readonly incarnation: string;
  readonly runId: string;
  /** The run's start: every hold it writes or clears is conditional on it. */
  readonly observedAt: string;
  readonly policy: SyncHoldPolicy;
  /** New holds may be written; false under `sync.holds=fail`, where content refusals fail the run as before. */
  readonly active: boolean;
  /** Holds outstanding when the run started, by path. */
  readonly existing: ReadonlyMap<string, GitHoldRecord>;
  readonly retryPaths: ReadonlySet<string>;
  /** Held paths this run re-screens though Git did not touch them. */
  readonly rescreen: string[];
  /** Held paths whose file is gone or no longer synced: cleared when the run settles. */
  readonly gone: string[];
  /** Retry requests this run took into its manifest. */
  readonly retryTaken: string[];
  /** Paths held this run; their failure-ledger rows resolve. */
  readonly heldPaths: string[];
  readonly recoveredPaths: string[];
  readonly counts: { screened: number; commentValues: number };
  /** #6188: fences Tier 1 normalized, and fences stored as written with issues (T5). */
  readonly fences: ReturnType<typeof importFenceTally>;
}

export type HoldScreen = { refusal: ContentRefusal | null; upstreamVersion: string | null };

/** The run's hold state, or null when holds do not apply (company-brain source, no source row). */
export async function openLegacyHolds(engine: BrainEngine, sourceId: string | undefined): Promise<LegacyHolds | null> {
  if (currentCompanyBrainSync(sourceId)) return null;
  const id = sourceId ?? DEFAULT_SOURCE_ID;
  const [row] = await engine.executeRaw<{ incarnation: string | null }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [id]).catch(() => []);
  if (!row?.incarnation) return null;
  const policy = await readSyncHoldPolicy(engine);
  const listed = await readGitSourceHolds(engine, { sourceIds: [id] });
  const retry = await readGitHoldRetryPaths(engine, id, row.incarnation);
  return {
    sourceId: id, incarnation: row.incarnation, runId: `legacy-${randomUUID()}`, observedAt: new Date().toISOString(), policy,
    active: policy.mode === 'hold', existing: new Map((listed[0]?.holds ?? []).map(record => [record.path, record])), retryPaths: new Set(retry),
    rescreen: [], gone: [], retryTaken: [], heldPaths: [], recoveredPaths: [], counts: { screened: 0, commentValues: 0 }, fences: importFenceTally(id),
  };
}

/** sha256 of the exact string legacy import reads (BOM stripped), or null when the file is over the size limit. */
function readImportContent(filePath: string): { content: string; upstreamVersion: string } | null {
  if (lstatSync(filePath).size > importSizeLimit(filePath)) return null;
  const content = readSourceFileSync(filePath, 'utf-8').replace(/^\uFEFF/, '');
  return { content, upstreamVersion: createHash('sha256').update(content).digest('hex') };
}

function currentVersion(filePath: string): string | null | undefined {
  try { return readImportContent(filePath)?.upstreamVersion ?? null; } catch { return undefined; }
}

/**
 * Picks the held paths this run re-screens though Git did not touch them:
 * changed bytes, or what the shared `holdRescreenDue` predicate names (a
 * retry request, an older frontmatter reader or fence screen, and holds whose
 * verdict depends on database state or the working tree). A held file that is
 * gone or no longer synced clears.
 * GBRA-133: a symlink, permission or absent-from-worktree hold is re-classified
 * every run and re-screened when its verdict changed (the link replaced by a
 * file, a chmod, a restore), with no commit needed; gone when the path left
 * the commit. `gitRoot` bounds a symlink target as in or out of the repository.
 * `selected` is null for a path outside this run's scope (left alone).
 */
export function planHoldRescreen(holds: LegacyHolds, input: { root: string; gitRoot?: string; touched: ReadonlySet<string>; selected: (path: string) => boolean | null }): void {
  for (const path of holds.retryPaths) if (!holds.existing.has(path)) holds.retryTaken.push(path);
  for (const [path, record] of holds.existing) {
    // GBRA-133: an unsupported_path hold stays while its exact bytes name a file, and clears once they do not.
    const byteGone = bytePathHoldGone(input.root, path);
    if (byteGone !== null) {
      if (byteGone) holds.gone.push(path);
      if (holds.retryPaths.has(path)) holds.retryTaken.push(path);
      continue;
    }
    if (input.touched.has(path)) {
      if (holds.retryPaths.has(path)) holds.retryTaken.push(path);
      continue;
    }
    const selected = input.selected(path);
    if (selected === null) continue;
    if (CLASSIC_FILE_HOLD_CODES.has(record.code)) {
      const now = selected ? classifyClassicFile(input.root, path, input.gitRoot ?? input.root) : null;
      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- path is a repo-relative hold path; lstat reads metadata only
      const present = (() => { try { return !!lstatSync(join(input.root, path)); } catch { return false; } })();
      if (!selected || (!now && !present)) {
        holds.gone.push(path);
      } else if (!holds.active || (now && now.code === record.code && now.reason === record.meta.reason && !holds.retryPaths.has(path))) {
        continue;
      } else {
        holds.rescreen.push(path);
      }
      if (holds.retryPaths.has(path)) holds.retryTaken.push(path);
      continue;
    }
    const filePath = fileUnderRoot(input.root, path);
    if (!selected || !filePath) {
      holds.gone.push(path);
      if (holds.retryPaths.has(path)) holds.retryTaken.push(path);
      continue;
    }
    if (!holds.active) continue;
    const due = holdRescreenDue(record, holds.retryPaths.has(path)) || currentVersion(filePath) !== record.upstream_version;
    if (!due) continue;
    holds.rescreen.push(path);
    if (holds.retryPaths.has(path)) holds.retryTaken.push(path);
  }
}

/**
 * The legacy import's content screen, read-only: the size, frontmatter and
 * slug checks `importFromFile` applies, for a rename destination before any
 * page moves and for dry runs. Code files and malformed names screen by size only.
 */
export function screenLegacyFile(filePath: string, relPath: string, activePack?: SyncActivePack): HoldScreen {
  let read: ReturnType<typeof readImportContent>;
  try {
    if (lstatSync(filePath).isSymbolicLink()) return { refusal: null, upstreamVersion: null };
    read = readImportContent(filePath);
  } catch {
    return { refusal: null, upstreamVersion: null };
  }
  if (!read) return { refusal: { code: 'file_too_large', message: `File too large (${lstatSync(filePath).size} bytes, max ${importSizeLimit(filePath)}).` }, upstreamVersion: null };
  if (hasMalformedPathSegment(relPath) || isCodeFilePath(relPath)) return { refusal: null, upstreamVersion: read.upstreamVersion };
  const parsed = parseMarkdown(read.content, relPath, { validate: true, ...(activePack ? { activePack } : {}) });
  const refusal = classifyImportHold(parsed, { expectedSlug: slugifyPath(relPath) || null, slugConflictMessage: (_found, expected) => slugConflictHoldMessage(relPath, expected) })
    ?? noncanonicalPrivateHold(read.content, parsed.frontmatter);
  return { refusal, upstreamVersion: read.upstreamVersion };
}

/**
 * The content refusal behind an import outcome; transient and conflict errors return null and keep failing.
 * #6188 (T5): legacy sync never holds for a fence; a fence refusal keeps today's outcome.
 */
export function legacyRefusal(result: Pick<ImportResult, 'status' | 'error' | 'refusal'>): ContentRefusal | null {
  if (result.status === 'imported') return null;
  if (result.refusal) return result.refusal.code === 'invalid_fence' ? null : result.refusal;
  const error = result.error ?? '';
  if (/^Content rejected by sanity gate: /.test(error)) return { code: 'content_rejected', message: error };
  if (/^purged_content: /.test(error)) return { code: 'purged_content', message: error };
  if (/^Refused by the write gate: /.test(error)) return { code: 'write_gate_rejected', message: error };
  const typed = isContentRefusal('invalid_params', error) ? contentRefusalFromReceipt('invalid_params', error) : null;
  if (!typed || typed.code === 'invalid_fence') return null;
  const { suggestion: _suggestion, ...refusal } = typed;
  return { ...refusal, message: error };
}

/** Records a hold for `path` (keeping a pending rename's identity) and reports it on stderr. */
export async function recordLegacyHold(engine: BrainEngine, holds: LegacyHolds, input: {
  path: string; refusal: Pick<ContentRefusal, 'message' | 'key' | 'line'> & { code: GitHoldCode; reason?: GitHoldReason };
  upstreamVersion: string | null; renameFrom?: SyncRename;
}): Promise<void> {
  const { path, refusal } = input;
  const renameFrom = input.renameFrom ?? holds.existing.get(path)?.meta.rename_from;
  const derived = resolveSlugForPath(path) || null;
  const [page] = renameFrom ? [] : await engine.executeRaw<{ id: number | string; slug: string }>(
    `SELECT id, slug FROM pages WHERE source_id=$1 AND deleted_at IS NULL AND (source_path=$2 OR slug=$3)
      ORDER BY (source_path=$2) DESC LIMIT 1`, [holds.sourceId, path, derived ?? '']);
  await engine.transaction(tx => writeGitHold(tx, {
    source_id: holds.sourceId, incarnation: holds.incarnation, path, source_path: path,
    slug: renameFrom?.slug ?? page?.slug ?? derived, page_id: renameFrom ? renameFrom.pageId : page ? Number(page.id) : null,
    code: refusal.code, message: refusal.message, upstream_version: input.upstreamVersion, observed_at: holds.observedAt,
    run_id: holds.runId, mode: 'legacy',
    meta: { ...(refusal.reason ? { reason: refusal.reason } : {}), ...(refusal.key ? { key: refusal.key } : {}),
      ...(refusal.line !== undefined ? { line: refusal.line } : {}), recovery_version: RECOVERY_VERSION, ...(renameFrom ? { rename_from: renameFrom } : {}) },
  }));
  holds.heldPaths.push(path);
  serr(`  Held ${sanitizePathForDisplay(path)} (${refusal.code}${refusal.reason ? `/${refusal.reason}` : ''}): not imported, the sync continues.`);
}

/** Holds the refused import result of `path`; false when it is not a content refusal (or holds are off). */
export async function holdRefusedImport(engine: BrainEngine, holds: LegacyHolds | null, path: string, filePath: string,
  result: Pick<ImportResult, 'status' | 'error' | 'refusal'>): Promise<boolean> {
  const refusal = holds?.active ? legacyRefusal(result) : null;
  if (!holds || !refusal) return false;
  try {
    const upstreamVersion = refusal.code === 'file_too_large' || !existsSync(filePath) ? null : readImportContent(filePath)?.upstreamVersion ?? null;
    await recordLegacyHold(engine, holds, { path, refusal, upstreamVersion });
    return true;
  } catch (e) {
    serr(`  Could not record the hold for ${sanitizePathForDisplay(path)} (${e instanceof Error ? e.message : String(e)}); it counts as a failure this run.`);
    return false;
  }
}

/** GBRA-133: holds a path classic sync cannot read as a regular file (or that is absent from the working tree); false when the hold cannot be recorded. */
export async function holdClassicFile(engine: BrainEngine, holds: LegacyHolds, path: string, refusal: ClassicFileHold): Promise<boolean> {
  try {
    await recordLegacyHold(engine, holds, { path, refusal, upstreamVersion: null });
    return true;
  } catch (e) {
    serr(`  Could not record the hold for ${sanitizePathForDisplay(path)} (${e instanceof Error ? e.message : String(e)}); it counts as a failure this run.`);
    return false;
  }
}

/** Bookkeeping for a screened import: the escalation denominator and the recovered-frontmatter tally. */
export function noteScreenedImport(holds: LegacyHolds | null, path: string, result: Pick<ImportResult, 'status' | 'frontmatter_recovery' | 'fences_normalized' | 'fence_issues'>): void {
  if (!holds) return;
  holds.counts.screened++;
  holds.fences.note(path, result);
  if (result.status !== 'imported' || !result.frontmatter_recovery) return;
  if (result.frontmatter_recovery.quoted) holds.recoveredPaths.push(path);
  if (result.frontmatter_recovery.comment_value) holds.counts.commentValues++;
}

/** Clears `path`'s hold after its import, no-op or deletion committed. */
export async function clearLegacyHold(engine: BrainEngine, holds: LegacyHolds | null, path: string): Promise<void> {
  if (!holds?.existing.has(path) || holds.heldPaths.includes(path)) return;
  await engine.transaction(tx => clearGitHold(tx, { sourceId: holds.sourceId, incarnation: holds.incarnation, path, observedAt: holds.observedAt }));
}

/** End of run: clear holds of gone files and of `paths` (deleted or renamed away), and drop the retry requests taken. */
export async function settleLegacyHolds(engine: BrainEngine, holds: LegacyHolds | null, paths: string[] = []): Promise<void> {
  if (!holds) return;
  for (const path of new Set([...holds.gone, ...paths])) await clearLegacyHold(engine, holds, path);
  await clearGitHoldRetryPaths(engine, holds.sourceId, holds.incarnation, [...new Set(holds.retryTaken)]);
}

/** The hold and recovered-frontmatter fields of the run's result. */
export async function legacyHoldFields(engine: BrainEngine, holds: LegacyHolds | null): Promise<Partial<SyncResult>> {
  if (!holds) return {};
  const report = await buildHoldReport(engine, { sourceId: holds.sourceId, incarnation: holds.incarnation, runId: holds.runId, remote: false,
    policy: holds.policy, screened: holds.counts.screened });
  const recovered = holds.recoveredPaths.length || holds.counts.commentValues
    ? recoveredReport(holds.sourceId, addRecovered(undefined, { paths: holds.recoveredPaths, commentValues: holds.counts.commentValues })) : undefined;
  const fences = holds.fences.fields();
  const normalized = fences.fences_normalized;
  if (normalized) await recordSyncRunTrend(engine, { sourceId: holds.sourceId, runId: holds.runId, day: new Date().toISOString().slice(0, 10), count: normalized.count,
    byClass: normalized.by_class as Record<string, number>, writers: Object.fromEntries(normalized.writers.map(w => [w.writer, w.count])) });
  return { ...report, ...(recovered ? { recovered_frontmatter: recovered } : {}), ...fences };
}

/** Dry run: the files this run would hold, read-only (no hold row is written or changed). */
export async function wouldHoldFields(engine: BrainEngine, holds: LegacyHolds | null, root: string, paths: string[], activePack?: SyncActivePack): Promise<Partial<SyncResult>> {
  if (!holds?.active) return { dry_run: true };
  const now = new Date().toISOString();
  const refused: Array<{ path: string; screen: HoldScreen & { refusal: ContentRefusal } }> = [];
  for (const path of new Set(paths)) {
    const filePath = fileUnderRoot(root, path);
    if (!filePath) continue;
    const screen = screenLegacyFile(filePath, path, activePack);
    if (screen.refusal) refused.push({ path, screen: screen as HoldScreen & { refusal: ContentRefusal } });
  }
  const pages = refused.length ? await engine.executeRaw<{ id: number | string; slug: string; source_path: string }>(
    'SELECT id, slug, source_path FROM pages WHERE source_id=$1 AND deleted_at IS NULL AND source_path = ANY($2::text[])',
    [holds.sourceId, refused.map(entry => entry.path)]) : [];
  const pageByPath = new Map(pages.map(page => [page.source_path, page]));
  const items: GitHoldItem[] = refused.map(({ path, screen }) => {
    const page = pageByPath.get(path);
    const { refusal } = screen;
    return gitHoldItem({ version: 1, source_id: holds.sourceId, incarnation: holds.incarnation, path, source_path: path,
      slug: page?.slug ?? (resolveSlugForPath(path) || null), page_id: page ? Number(page.id) : null, code: refusal.code, message: refusal.message,
      upstream_version: screen.upstreamVersion, observed_at: now, held_at: holds.existing.get(path)?.held_at ?? now, updated_at: now, run_id: null, mode: 'legacy',
      meta: { ...(refusal.reason ? { reason: refusal.reason } : {}), ...(refusal.key ? { key: refusal.key } : {}),
        ...(refusal.line !== undefined ? { line: refusal.line } : {}), recovery_version: RECOVERY_VERSION } });
  });
  return { dry_run: true, would_hold: items.slice(0, holds.policy.cap), would_hold_count: items.length };
}

/**
 * Folds the holds into the run's manifest: a held rename destination that is
 * re-screened (or touched by Git) becomes a rename from its recorded origin,
 * so the page moves with its id once the file imports; a rename away from a
 * held destination (`a -> b (held) -> c`) carries the original origin forward.
 */
export function applyHoldsToManifest(holds: LegacyHolds | null, filtered: { added: string[]; modified: string[]; renamed: Array<{ from: string; to: string }> }): void {
  if (!holds?.active) return;
  const pending = (path: string) => holds.existing.get(path)?.meta.rename_from;
  for (const rename of filtered.renamed) {
    const origin = pending(rename.from);
    if (!origin) continue;
    holds.gone.push(rename.from);
    rename.from = origin.sourcePath;
  }
  for (const list of [filtered.added, filtered.modified, holds.rescreen]) {
    for (let i = list.length - 1; i >= 0; i--) {
      const origin = pending(list[i]!);
      if (!origin) continue;
      filtered.renamed.push({ from: origin.sourcePath, to: list[i]! });
      list.splice(i, 1);
    }
  }
}

/** GBRA-133 S-51: the hold code of a rename pair whose identity the database refused to read. */
const UNREADABLE_RENAME = 'rename_identity_unreadable';

/**
 * GBRA-133 S-51: holds each pair the identity confirmation could not read (SQLSTATE 22021/22P05). `to` is not
 * imported and the page at `from` keeps its id, links, facts and timeline; the hold records that page, so the pair
 * moves with its id if a later decision confirms it.
 */
export async function holdUnreadableRenames(engine: BrainEngine, holds: LegacyHolds, root: string, pairs: Array<{ from: string; to: string; cause: unknown }>): Promise<void> {
  for (const pair of pairs) {
    const [page] = await engine.executeRaw<{ id: number | string; slug: string; revision: string }>(
      `SELECT id, slug, knowledge_revision::text AS revision FROM pages WHERE source_id=$1 AND deleted_at IS NULL AND (source_path=$2 OR slug=$3)
        ORDER BY (source_path=$2) DESC LIMIT 1`, [holds.sourceId, pair.from, resolveSlugForPath(pair.from) || '']);
    const filePath = fileUnderRoot(root, pair.to);
    const state = (pair.cause as { code?: unknown } | null)?.code;
    await recordLegacyHold(engine, holds, {
      path: pair.to, upstreamVersion: filePath ? currentVersion(filePath) ?? null : null,
      renameFrom: page ? { sourcePath: pair.from, slug: page.slug, pageId: Number(page.id), revision: page.revision } : undefined,
      refusal: { code: UNREADABLE_RENAME, message: `${pair.to} replaces ${pair.from} in this sync, but the database refused to compare its title or id`
        + `${typeof state === 'string' ? ` (SQLSTATE ${state})` : ''}, so sync could not tell whether it is the same page; it held ${pair.to} and kept the old page.` },
    });
  }
}

/**
 * GBRA-133 S-51: a held pair whose file this run imports or re-screens is decided again before the hold replay turns
 * it into a rename. Confirmed: the replay moves the page with its id. Downgraded: the old page is deleted and the file
 * imports as a new page, as for any unconfirmed pair. Still unreadable: it stays held and is not imported.
 */
export async function redecideUnreadableRenames(engine: BrainEngine, holds: LegacyHolds, root: string, filtered: { added: string[]; modified: string[]; deleted: string[] },
  decide: (pair: { from: string; to: string; pageId: number }) => Promise<'confirmed' | 'downgraded' | 'held'>): Promise<void> {
  if (!holds.active) return;
  const existing = holds.existing as Map<string, GitHoldRecord>;
  for (const [path, record] of existing) {
    const origin = record.meta.rename_from;
    const lists = [filtered.added, filtered.modified, holds.rescreen];
    if (record.code !== UNREADABLE_RENAME || !origin || !lists.some(list => list.includes(path))) continue;
    const verdict = await decide({ from: origin.sourcePath, to: path, pageId: origin.pageId });
    if (verdict === 'confirmed') continue;
    if (verdict === 'downgraded') {
      const { rename_from: _settled, ...meta } = record.meta;
      existing.set(path, { ...record, meta });
      if (!filtered.deleted.includes(origin.sourcePath)) filtered.deleted.push(origin.sourcePath);
      continue;
    }
    for (const list of lists) { const at = list.indexOf(path); if (at >= 0) list.splice(at, 1); }
    const filePath = fileUnderRoot(root, path);
    await recordLegacyHold(engine, holds, { path, upstreamVersion: filePath ? currentVersion(filePath) ?? null : null, renameFrom: origin,
      refusal: { code: UNREADABLE_RENAME, message: record.message } });
  }
}

/** The rename a hold on `to` (or on an earlier destination of the same origin) still owes. */
function pendingRename(holds: LegacyHolds, from: string, to: string): SyncRename | undefined {
  return holds.existing.get(to)?.meta.rename_from
    ?? [...holds.existing.values()].find(record => record.meta.rename_from?.sourcePath === from)?.meta.rename_from;
}

async function currentPage(engine: BrainEngine, sourceId: string, where: { id: number } | { slug: string }): Promise<{ id: number; slug: string; revision: string } | undefined> {
  const [row] = await engine.executeRaw<{ id: number | string; slug: string; revision: string }>(
    `SELECT id, slug, knowledge_revision::text AS revision FROM pages WHERE source_id=$1 AND deleted_at IS NULL AND ${'id' in where ? 'id=$2' : 'slug=$2'}`,
    [sourceId, 'id' in where ? where.id : where.slug]);
  return row ? { id: Number(row.id), slug: row.slug, revision: row.revision } : undefined;
}

/**
 * E13: screens a rename destination before the old page's slug or origin
 * moves. True when the destination is held: the old page keeps its slug and
 * origin, and the hold records the rename so the page moves with its id once
 * the file imports. A pending rename whose old page changed since stays held
 * as `rename_held` instead of overwriting those changes.
 */
export async function holdRenameDestination(engine: BrainEngine, holds: LegacyHolds | null,
  input: { from: string; to: string; filePath: string; oldSlug: string | undefined; activePack?: SyncActivePack }): Promise<boolean> {
  if (!holds?.active || !existsSync(input.filePath)) return false;
  const pending = pendingRename(holds, input.from, input.to);
  const screen = screenLegacyFile(input.filePath, input.to, input.activePack);
  if (screen.refusal) {
    const page = pending || input.oldSlug === undefined ? undefined : await currentPage(engine, holds.sourceId, { slug: input.oldSlug });
    const renameFrom = pending ?? (page ? { sourcePath: input.from, slug: page.slug, pageId: page.id, revision: page.revision } : undefined);
    await recordLegacyHold(engine, holds, { path: input.to, refusal: screen.refusal, upstreamVersion: screen.upstreamVersion, renameFrom });
    return true;
  }
  if (!pending) return false;
  const current = await currentPage(engine, holds.sourceId, { id: pending.pageId });
  if (!current || (current.slug === pending.slug && current.revision === pending.revision)) return false;
  await holdChangedRename(engine, holds, input.to, pending, screen.upstreamVersion);
  return true;
}

/** Holds a rename destination whose old page changed after the rename was recorded: moving it would overwrite those changes. */
async function holdChangedRename(engine: BrainEngine, holds: LegacyHolds, to: string, renameFrom: SyncRename, upstreamVersion: string | null): Promise<void> {
  await recordLegacyHold(engine, holds, { path: to, upstreamVersion, renameFrom, refusal: { code: 'rename_held', reason: 'rename_source_changed',
    message: `${to} is a rename of page ${renameFrom.slug}, which changed after the rename was recorded, so the page was not moved onto the new file.` } });
}

/**
 * Full sync: a held rename destination that now screens clean moves its page
 * (same id) before the walk imports it. One whose old page changed since is
 * held as `rename_held` (the walk skips it), never imported as a second page.
 */
export async function moveHeldRenames(engine: BrainEngine, holds: LegacyHolds | null, root: string): Promise<void> {
  if (!holds?.active) return;
  for (const record of holds.existing.values()) {
    const origin = record.meta.rename_from;
    const filePath = fileUnderRoot(root, record.path);
    if (!origin || !filePath) continue;
    const screen = screenLegacyFile(filePath, record.path);
    if (screen.refusal) continue;
    const current = await currentPage(engine, holds.sourceId, { id: origin.pageId });
    if (!current) continue;
    if (current.slug !== origin.slug || current.revision !== origin.revision) {
      await holdChangedRename(engine, holds, record.path, origin, screen.upstreamVersion);
      continue;
    }
    try {
      const slug = resolveSlugForPath(record.path);
      await maintenanceBeliefTransaction(engine, { sourceId: holds.sourceId, slugs: [origin.slug, slug], op: 'sync_rename' }, async tx => {
        if (await tx.updateSlug(origin.slug, slug, { sourceId: holds.sourceId }) === 0) return;
        await bindOrigin(tx, { sourceId: holds.sourceId, pageId: origin.pageId, sourcePath: record.path });
      });
    } catch { /* the walk imports the file as an ordinary add; the old page stays until a full walk proves it gone */ }
  }
}

/**
 * Full sync is authoritative for the tree it walked: a held path it walked
 * without holding or failing (imported, unchanged or no longer refused), or
 * whose file is gone, clears; every retry request was re-screened.
 */
export async function settleFullSyncHolds(engine: BrainEngine, holds: LegacyHolds | null, input: { root: string; walked: ReadonlySet<string>; failed: ReadonlySet<string> }): Promise<void> {
  if (!holds) return;
  for (const path of holds.existing.keys()) {
    if (input.failed.has(path)) continue;
    if (bytePathHoldGone(input.root, path) ?? (input.walked.has(path) || !fileUnderRoot(input.root, path))) await clearLegacyHold(engine, holds, path);
  }
  holds.retryTaken.push(...holds.retryPaths);
  await settleLegacyHolds(engine, holds);
}

/** Origins of pages a held rename still owes; a full walk never deletes them. */
export async function heldRenameOrigins(engine: BrainEngine, sourceId: string): Promise<Set<string>> {
  const listed = await readGitSourceHolds(engine, { sourceIds: [sourceId] });
  return new Set((listed[0]?.holds ?? []).flatMap(record => record.meta.rename_from ? [record.meta.rename_from.sourcePath] : []));
}