Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
18.8 KB
Raw Blame
/**
 * #6729: inexact Git renames a sync could not confirm (see sync-rename-identity.ts) were split into a delete plus an
 * add, so the old page's facts, links and aliases stay on its soft-deleted slug. Each one is recorded here until the
 * pair gets a disposition: `gbrain sync status --json` lists it, doctor `rename_identity_downgrades` names it, the purge
 * leaves its old page alone and the checkpoint sweep keeps the record while it is open, and the report names the
 * restore of the old page. There is no time window: a pair recorded before its remedy exists can still be repaired.
 *
 * One `op_checkpoints` row per old page (op `sync-identity-downgrade`, fingerprint = the old page id);
 * `completed_keys[0]` holds the record. A record is open while it has no `disposition` (set when the pair is remedied
 * or closed without merging) and its old page is still soft-deleted from that sync (`deleted_at` = `old_deleted_at`);
 * a restore, a purge or a later delete of the restored page closes it.
 *
 * Every surface names the remedy per pair (`identityRemedy`): the preview `gbrain repair rename-identity --source <id>
 * --slug <new>`, its apply with the plan hash (destructive consent), and what releases the purge hold. On a managed brain
 * carrying identity is unavailable (`managed_remedy_unavailable`), so the remedy there is `--close`.
 */
import type { BrainEngine } from './engine.ts';
import { isConnectorSourceKind } from './persistence/connector-identity.ts';
import { getWorktreeBinding } from './persistence/ownership.ts';
import { readDatabaseOnlyActivatedSources } from './persistence/unbound-source.ts';
import { readManagedMode } from './persistence/managed-mode.ts';
import { previewHash } from './persistence/preview-approval.ts';
import { canonicalOriginPage, pickCanonicalOrigin } from './persistence/origin-guard.ts';
import { resolveSlugForPath, type DowngradedRename, type RenameDowngradeReason } from './sync.ts';

export const IDENTITY_DOWNGRADE_OP = 'sync-identity-downgrade';

export interface IdentityDowngrade extends DowngradedRename {
  source_id: string;
  /** The soft-deleted page the old file backed, and the page the new file imported to (null when it did not import). */
  old_slug: string; old_page_id: number; new_slug: string | null;
  /** What stays on the old slug: facts keyed to it, links from or to it, and its free-text aliases. */
  facts: number; links: number; aliases: number;
  /** When the old page was soft-deleted (ISO), and that `deleted_at` exactly as Postgres printed it (the open test). */
  recorded_at: string; old_deleted_at: string;
  /** Set when the pair is remedied or closed without merging; the record is then closed. */
  disposition?: { kind: 'remedied' | 'closed'; at: string };
  /** Read live: whether `gbrain restore` can write the old page back on this source (see `identityRestoreAvailable`). */
  restore_available?: boolean;
}

type RestoreProbeEngine = Pick<BrainEngine, 'executeRaw' | 'getConfig' | 'kind'>;

/**
 * Whether a restore of a page that came from a canonical file can be admitted on this source, by the rule page writes
 * follow (decideUnboundWrite): a bound source, a connector source, a source with no checkout, or a PGLite source not
 * activated database-only can; an unbound Postgres source with a checkout refuses `owner_unavailable`, so no surface
 * offers the restore there.
 */
export async function identityRestoreAvailable(engine: RestoreProbeEngine, sourceId: string): Promise<boolean> {
  const [source] = await engine.executeRaw<{ local_path: string | null; kind: string | null }>("SELECT local_path, config->>'kind' AS kind FROM sources WHERE id = $1", [sourceId]);
  if (!source?.local_path || isConnectorSourceKind(source.kind)) return true;
  if (await getWorktreeBinding(engine as never, sourceId, null)) return true;
  return engine.kind === 'pglite' && !(await readDatabaseOnlyActivatedSources(engine)).includes(sourceId);
}

/** SQL: the downgrade record `dg` is open for the page aliased `alias` (no disposition, old page still soft-deleted by that sync). */
export const identityDowngradeOpen = (alias: string): string =>
  `dg.completed_keys->0->>'disposition' IS NULL AND ${alias}.deleted_at = (dg.completed_keys->0->>'old_deleted_at')::timestamptz`;

/** SQL predicate for a purge scan over `pages` aliased `alias`: the page has no open downgrade record. */
export function identityDowngradePurgeHold(alias: string): string {
  return `NOT EXISTS (SELECT 1 FROM op_checkpoints dg WHERE dg.op = '${IDENTITY_DOWNGRADE_OP}' AND dg.fingerprint = ${alias}.id::text
    AND ${identityDowngradeOpen(alias)})`;
}

const REASON_TEXT: Record<RenameDowngradeReason, string> = {
  id_conflict: 'the two files carry different frontmatter ids',
  id_shared: 'their frontmatter id is also carried by another file or page',
  id_one_side: 'only one side carries a frontmatter id',
  title_not_unique: 'their shared title is not unique',
  slug_not_unique: 'their shared slug: line is not unique',
  no_identity_signal: 'no frontmatter id, slug: or title matches',
};
export const identityDowngradeReasonText = (reason: RenameDowngradeReason): string => REASON_TEXT[reason];

/**
 * Records the downgraded pairs of a finished sync (paths in the source's origin form). A pair whose old page is not
 * soft-deleted (the delete did not land, or the old file never imported) has nothing to carry and is not recorded.
 */
export async function recordIdentityDowngrades(engine: BrainEngine, sourceId: string, pairs: DowngradedRename[]): Promise<IdentityDowngrade[]> {
  const records: IdentityDowngrade[] = [];
  for (const pair of pairs) {
    const [old] = await engine.executeRaw<{ id: number | string; slug: string; deleted_at: string }>(
      `SELECT id, slug, deleted_at::text AS deleted_at FROM pages WHERE source_id = $1 AND deleted_at IS NOT NULL
        AND (source_path = $2 OR (source_path IS NULL AND slug = $3)) ORDER BY deleted_at DESC LIMIT 1`,
      [sourceId, pair.from, resolveSlugForPath(pair.from)]);
    if (!old) continue;
    const owner = await canonicalOriginPage(engine, sourceId, pair.to);
    const fresh = owner && !('ambiguous' in owner) ? owner : null;
    const [counts] = await engine.executeRaw<{ facts: number | string; links: number | string; aliases: number | string }>(`SELECT
        (SELECT count(*) FROM facts WHERE source_id = $1 AND entity_slug = $2) AS facts,
        (SELECT count(*) FROM links WHERE from_page_id = $3 OR to_page_id = $3) AS links,
        (SELECT count(*) FROM page_aliases WHERE source_id = $1 AND slug = $2) AS aliases`, [sourceId, old.slug, Number(old.id)]);
    const recorded = new Date(old.deleted_at);
    const record: IdentityDowngrade = { source_id: sourceId, from: pair.from, to: pair.to, similarity: pair.similarity, reason: pair.reason, ...(pair.read ? { read: pair.read } : {}),
      old_slug: old.slug, old_page_id: Number(old.id), new_slug: fresh?.slug ?? null,
      facts: Number(counts?.facts ?? 0), links: Number(counts?.links ?? 0), aliases: Number(counts?.aliases ?? 0),
      recorded_at: recorded.toISOString(), old_deleted_at: old.deleted_at };
    await engine.executeRaw(`INSERT INTO op_checkpoints (op, fingerprint, completed_keys, updated_at) VALUES ($1, $2, $3::text::jsonb, now())
      ON CONFLICT (op, fingerprint) DO UPDATE SET completed_keys = EXCLUDED.completed_keys, updated_at = now()`,
      [IDENTITY_DOWNGRADE_OP, String(record.old_page_id), JSON.stringify([record])]);
    records.push(record);
  }
  return records;
}

/**
 * Open records (no disposition, old page still soft-deleted by that sync), oldest first; every source when `sourceIds` is omitted.
 * `new_slug` is read live: the live page at the new path now (a held new file that was fixed later counts once it imports).
 */
export async function listIdentityDowngrades(engine: RestoreProbeEngine, sourceIds?: readonly string[]): Promise<IdentityDowngrade[]> {
  const rows = await engine.executeRaw<{ record: IdentityDowngrade | string; new_slugs: string[] | null }>(
    `SELECT dg.completed_keys->0 AS record, np.slugs AS new_slugs FROM op_checkpoints dg JOIN pages p ON p.id::text = dg.fingerprint
      LEFT JOIN LATERAL (SELECT array_agg(slug ORDER BY slug) AS slugs FROM pages WHERE source_id = p.source_id AND deleted_at IS NULL AND source_path = dg.completed_keys->0->>'to') np ON true
      WHERE dg.op = $1 AND p.deleted_at IS NOT NULL AND ${identityDowngradeOpen('p')}
        AND p.source_id = dg.completed_keys->0->>'source_id' AND ($2::text[] IS NULL OR p.source_id = ANY($2::text[]))
      ORDER BY dg.completed_keys->0->>'recorded_at', dg.fingerprint`, [IDENTITY_DOWNGRADE_OP, sourceIds ? [...sourceIds] : null]);
  const records = rows.map(row => {
    const record = typeof row.record === 'string' ? JSON.parse(row.record) as IdentityDowngrade : row.record;
    const owner = pickCanonicalOrigin((row.new_slugs ?? []).map(slug => ({ slug })), record.to);
    return { ...record, new_slug: owner && !('ambiguous' in owner) ? owner.slug : null };
  });
  const restorable = new Map<string, boolean>();
  for (const sourceId of new Set(records.map(record => record.source_id))) restorable.set(sourceId, await identityRestoreAvailable(engine, sourceId));
  return records.map(record => ({ ...record, restore_available: restorable.get(record.source_id)! }));
}

/** What the remedy does with a pair: carry the old page's identity onto the new slug (default), or close the record. */
export type IdentityRemedyDisposition = 'carry' | 'close';
export const IDENTITY_HOLD_RELEASE = 'the remedy carries or closes the pair, or the old page is restored or purged';
/** A carry is a classic-source maintenance transaction; on a managed brain the remedy can only close the pair. */
export const MANAGED_REMEDY_UNAVAILABLE = 'managed_remedy_unavailable';

/** One page side of a pair as the remedy binds it: id, slug, revision and whether it is soft-deleted. */
export interface IdentityRemedySide { page_id: number; slug: string; revision: string; deleted: boolean }

/** The per-pair remedy every surface prints (sync report, `sync status --json`, doctor). */
export interface IdentityRemedy {
  /** `carry`, or `close` when the new file did not import or carrying is unavailable. */
  disposition: IdentityRemedyDisposition;
  /** `managed_remedy_unavailable` on a managed brain (the pair can only be closed there), else null. */
  carry_unavailable: typeof MANAGED_REMEDY_UNAVAILABLE | null;
  plan_hash: string; preview_argv: string[]; argv: string[]; consent: ['destructive'];
  hold_releases: string;
}

export type IdentityDowngradeEntry = IdentityDowngrade & { remedy: IdentityRemedy };

async function remedySide(engine: Pick<BrainEngine, 'executeRaw'>, sourceId: string, where: string, value: string | number): Promise<IdentityRemedySide | null> {
  const [row] = await engine.executeRaw<{ id: number | string; slug: string; revision: string | null; deleted: boolean }>(
    `SELECT id, slug, knowledge_revision::text AS revision, deleted_at IS NOT NULL AS deleted FROM pages WHERE source_id = $1 AND ${where} = $2 LIMIT 1`, [sourceId, value]);
  return row ? { page_id: Number(row.id), slug: row.slug, revision: row.revision ?? '', deleted: row.deleted === true } : null;
}

/**
 * The state a remedy preview binds: the brain, the pair, both page ids and revisions, and the disposition. The old page
 * is read by id (it may have moved since), the new page by its live slug. Every surface hashes these same parts, so the
 * hash a sync report or doctor prints is the one the preview saves.
 */
export async function identityRemedyParts(engine: Pick<BrainEngine, 'executeRaw'>, record: IdentityDowngrade, disposition: IdentityRemedyDisposition) {
  const [brain] = await engine.executeRaw<{ brain_id: string }>('SELECT brain_id FROM persistence_brain WHERE singleton=1').catch(() => []);
  const old = await remedySide(engine, record.source_id, 'id', record.old_page_id);
  const fresh = record.new_slug ? await remedySide(engine, record.source_id, 'slug', record.new_slug) : null;
  return { kind: 'rename-identity-v1', brain_id: brain?.brain_id ?? 'host', source_id: record.source_id, from: record.from, to: record.to,
    recorded_at: record.recorded_at, disposition, old, new: fresh && !fresh.deleted ? fresh : null };
}
export type IdentityRemedyParts = Awaited<ReturnType<typeof identityRemedyParts>>;

/** `gbrain repair rename-identity --source <id> --slug <new>` (`--from <old>` when another open pair shares the new slug). */
export function renameIdentityPreviewArgv(record: Pick<IdentityDowngrade, 'source_id' | 'new_slug' | 'old_slug'>, opts: { from?: boolean; close?: boolean } = {}): string[] {
  return ['gbrain', 'repair', 'rename-identity', '--source', record.source_id, ...(record.new_slug ? ['--slug', record.new_slug] : []),
    ...(opts.from || !record.new_slug ? ['--from', record.old_slug] : []), ...(opts.close ? ['--close'] : [])];
}

/** The remedy one pair names: its preview, the apply bound to the current plan hash, consent, and the hold release. */
export async function identityRemedy(engine: Pick<BrainEngine, 'executeRaw'>, record: IdentityDowngrade, opts: { from?: boolean; managed?: boolean } = {}): Promise<IdentityRemedy> {
  const close = !!opts.managed || !record.new_slug;
  const plan_hash = previewHash(await identityRemedyParts(engine, record, close ? 'close' : 'carry'));
  const preview_argv = renameIdentityPreviewArgv(record, { from: opts.from, close });
  return { disposition: close ? 'close' : 'carry', carry_unavailable: opts.managed && record.new_slug ? MANAGED_REMEDY_UNAVAILABLE : null,
    plan_hash, preview_argv, argv: [...preview_argv, '--apply', '--expect', plan_hash, '--yes'], consent: ['destructive'], hold_releases: IDENTITY_HOLD_RELEASE };
}

/** Each record with its remedy; `--from` is named only where two open pairs share a new slug. */
export async function withIdentityRemedies(engine: Pick<BrainEngine, 'executeRaw'>, records: readonly IdentityDowngrade[]): Promise<IdentityDowngradeEntry[]> {
  if (!records.length) return [];
  const managed = await readManagedMode(engine);
  const shared = (record: IdentityDowngrade) => records.filter(other => other.source_id === record.source_id && other.new_slug === record.new_slug).length > 1;
  return Promise.all(records.map(async record => ({ ...record, remedy: await identityRemedy(engine, record, { from: shared(record), managed }) })));
}

/** How the remedy settled a pair: its identity was carried (`remedied`) or its record closed (`closed`). */
export type IdentityDowngradeSettlement = 'remedied' | 'closed';

/**
 * Settles one open record (disposition still unset) with `completed_keys[0].disposition = { kind, at }`, so the purge no
 * longer waits for its old page and no surface lists it. Returns the rows settled (0 when already settled or gone).
 */
export async function settleIdentityDowngrade(engine: Pick<BrainEngine, 'executeRaw'>, oldPageId: number, kind: IdentityDowngradeSettlement): Promise<number> {
  return (await engine.executeRaw(
    `UPDATE op_checkpoints SET completed_keys = jsonb_set(completed_keys, '{0,disposition}', jsonb_build_object('kind', $3::text, 'at', $4::text))
      WHERE op = $1 AND fingerprint = $2 AND completed_keys->0->>'disposition' IS NULL RETURNING 1`,
    [IDENTITY_DOWNGRADE_OP, String(oldPageId), kind, new Date().toISOString()])).length;
}

/** A recorded downgrade (as opposed to a raw pair a sync has not recorded yet). */
export const isRecordedDowngrade = (entry: DowngradedRename): entry is IdentityDowngrade => 'old_page_id' in entry;

/**
 * After a sync that committed (synced or first sync, not a dry run): records its downgraded pairs, prints the report
 * lines, and returns the result with the recorded entries in place of the raw pairs. A recording failure is one line
 * and never fails the sync.
 */
export async function noteIdentityDowngrades<T extends { status: string; identityDowngrades?: DowngradedRename[] }>(engine: BrainEngine, sourceId: string,
  result: T, write: (line: string) => void): Promise<T> {
  const pairs = (result.identityDowngrades ?? []).filter(pair => !isRecordedDowngrade(pair));
  if (!pairs.length || !['synced', 'first_sync'].includes(result.status)) return result;
  try {
    const restore_available = await identityRestoreAvailable(engine, sourceId);
    const records = await withIdentityRemedies(engine, (await recordIdentityDowngrades(engine, sourceId, pairs)).map(record => ({ ...record, restore_available })));
    for (const line of identityDowngradeLines(records)) write(line);
    return { ...result, identityDowngrades: records };
  } catch (error) {
    write(`  Could not record ${pairs.length} rename(s) whose identity was not kept: ${error instanceof Error ? error.message : String(error)}`);
    return result;
  }
}

/**
 * Restores one old page with its facts, links and aliases, beside the new page. Where the restore cannot re-create the
 * old file, it refuses `canonical_file_absent` and names `--detach` (database-only) as the user's choice.
 */
export const identityRestoreArgv = (record: Pick<IdentityDowngrade, 'source_id' | 'old_slug'>): string[] =>
  ['gbrain', 'restore', record.old_slug, '--source-id', record.source_id, '--force'];
/** The read-only listing of a source's open records. */
export const identityStatusArgv = (sourceId: string): string[] => ['gbrain', 'sync', 'status', '--source', sourceId, '--json'];

/** What the remedy of one pair does, for the report line and doctor. */
export function remedyAction(record: IdentityDowngradeEntry): string {
  if (record.remedy.disposition === 'carry') return `Carry ${record.old_slug}'s identity onto ${record.new_slug} (asks the user first: destructive)`;
  if (record.remedy.carry_unavailable) return `Carrying ${record.old_slug}'s identity onto ${record.new_slug} is unavailable on a managed source (${record.remedy.carry_unavailable}); `
    + 'release the purge hold without carrying it (asks the user first: destructive)';
  return 'Release the purge hold (asks the user first: destructive)';
}

/** The sync report's lines for the downgraded pairs of one run, each naming its remedy. */
export function identityDowngradeLines(records: readonly IdentityDowngradeEntry[]): string[] {
  if (!records.length) return [];
  return [
    ...records.flatMap(record => [`  Identity not kept: ${record.from} -> ${record.to} (git similarity ${record.similarity}%; ${REASON_TEXT[record.reason]}). `
      + `${record.facts} fact(s), ${record.links} link(s) and ${record.aliases} alias(es) stay on the soft-deleted ${record.old_slug}; `
      + `${record.new_slug ? `${record.new_slug} starts fresh.` : 'the new file did not import.'} The purge holds ${record.old_slug} until ${record.remedy.hold_releases}.`,
    `    ${remedyAction(record)}: preview ${record.remedy.preview_argv.join(' ')}, then apply ${record.remedy.argv.join(' ')}`
      + (record.restore_available === false ? '' : `; or keep ${record.old_slug} as its own page: ${identityRestoreArgv(record).join(' ')}`)]),
    '  A move keeps its page when the files share a frontmatter id: (or a unique slug: line or title); to move and rewrite a page, move, commit and sync, then edit.',
  ];
}