Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.1 KB
Raw Blame
/**
 * #6948: the one owner of origin assignment. A page's origin is the file it
 * records (`pages.source_id`, `pages.source_path`); two live pages of a source
 * recording the same origin ("twins") make sync discovery refuse that file. The
 * partial unique index `pages_live_origin_key` makes twins impossible where it
 * exists; on a brain whose existing twins keep the migration from building it,
 * this guard is the protection. Every write that makes a page a live claimant of
 * an origin it did not live-claim before (an assignment, an insert carrying an
 * origin, a tombstone revival) runs `assertOriginUnclaimed` in its own
 * transaction, serialized on the origin by a transaction-scoped advisory lock.
 * A write that keeps the page's own origin is not an assignment.
 */
import { existsSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import { opError, type OperationError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { resolveSlugForPath } from '../sync.ts';
import { sameSyncOrigin, syncOriginPath, syncOriginScope, type SyncOriginScope } from './sync-origin.ts';

export const ORIGIN_INDEX_NAME = 'pages_live_origin_key';

type Exec = Pick<BrainEngine, 'executeRaw'>;

/** The page a write targets (by id, else by slug; absent for an insert) and the origin it would record (null: it keeps its stored origin). */
export interface OriginTarget {
  sourceId: string;
  sourcePath?: string | null;
  pageId?: number | null;
  slug?: string;
  /** The write makes a soft-deleted target live again (putPage's ON CONFLICT, restorePage, a segmented flip). */
  revive?: boolean;
  /** The source's origin form when the caller has it; omitted, it is read from the source row; null skips the legacy spelling. */
  scope?: SyncOriginScope | null;
}

interface TargetRow { id: number; slug: string; source_path: string | null; deleted_at: unknown }

/** The read-only preview of the origin-twin repair, which names the page that keeps the file. */
export function originTwinsFix(sourceId: string) {
  return readFix(`Previews which page of source ${sourceId} keeps each shared origin; read-only.`, { argv: ['gbrain', 'repair', 'origin-twins', '--source', sourceId] });
}

export function originAlreadyClaimed(sourceId: string, sourcePath: string, holders: readonly string[], target?: string): OperationError {
  const held = holders.length ? `Page ${holders.join(', ')} already records` : 'Another live page already records';
  return opError('page_identity_changed', `Another live page of source ${sourceId} already records ${JSON.stringify(sourcePath)} as its origin.`,
    `${held} ${JSON.stringify(sourcePath)} in source ${sourceId}, so ${target ? `page ${target}` : 'this page'} cannot become a second page of that file; nothing was written. `
    + `Write to the page that records the file, or preview gbrain repair origin-twins --source ${sourceId} to see which page keeps it.`,
    { detail: 'origin_already_claimed', fix: originTwinsFix(sourceId) });
}

/** A reader's refusal to pick one of several live pages recording a file (`origin_conflict`). */
export function originConflictMessage(sourceId: string, sourcePath: string, slugs: readonly string[]): string {
  return `${sourcePath} is recorded by several live pages of source ${sourceId} (${slugs.join(', ')}) and none is its canonical page, so nothing was written into either. `
    + `Preview gbrain repair origin-twins --source ${sourceId}, apply the merge it proposes, then preview this repair again.`;
}

/** Whether `error` is the guard's refusal (or a mapped index violation). */
export function isOriginClaimRefusal(error: unknown): boolean {
  return typeof error === 'object' && error !== null && (error as { detail?: unknown }).detail === 'origin_already_claimed';
}

/** A 23505 on `pages_live_origin_key` (both engines' error shapes), as the guard's own refusal; null for anything else. */
export function classifyOriginUniqueViolation(error: unknown, at?: { sourceId: string; sourcePath: string; slug?: string }): OperationError | null {
  if (!error || typeof error !== 'object') return null;
  const e = error as Record<string, unknown>;
  if (String(e.code) !== '23505' || (e.constraint_name ?? e.constraint) !== ORIGIN_INDEX_NAME) return null;
  const key = /=\((.*), (.*)\) already exists/.exec(typeof e.detail === 'string' ? e.detail : '');
  return originAlreadyClaimed(at?.sourceId ?? key?.[1] ?? 'unknown', at?.sourcePath ?? key?.[2] ?? 'unknown', [], at?.slug);
}

function gitRootOf(path: string): string | null {
  for (let dir = resolve(path); ; dir = dirname(dir)) {
    if (existsSync(join(dir, '.git'))) return dir;
    if (dirname(dir) === dir) return null;
  }
}

/** The origin form of a source pinned to source-root slugs at a subdirectory of its repository; undefined otherwise. */
async function originScopeOf(tx: Exec, sourceId: string): Promise<SyncOriginScope | undefined> {
  const [source] = await tx.executeRaw<{ local_path: string | null; mode: string | null }>(
    "SELECT local_path, config->>'slug_root_mode' AS mode FROM sources WHERE id=$1", [sourceId]);
  if (!source?.local_path || source.mode !== 'source-root' || !existsSync(source.local_path)) return undefined;
  const gitRoot = gitRootOf(source.local_path);
  return gitRoot ? syncOriginScope({ sourceId, root: source.local_path, gitRoot, slugMode: 'source-root' }) : undefined;
}

const originKey = (path: string) => process.platform === 'win32' ? path.replaceAll('\\', '/').toLowerCase() : path;
/** The lock key of one spelling: `syncOriginPath`'s normal form folded as `originKey` compares it (a path it refuses keeps its raw spelling). */
const lockKey = (path: string) => { try { return originKey(syncOriginPath(path)); } catch { return originKey(path); } };

/** Whether `recorded` (stored on the page `recordedSlug`) names the same file as `origin`: the same spelling, or the legacy Git-root spelling of either. */
function sameOrigin(recorded: string, recordedSlug: string | undefined, origin: string, originSlug: string | undefined, scope: SyncOriginScope | undefined): boolean {
  if (originKey(recorded) === originKey(origin)) return true;
  const prefix = scope?.slugMode === 'source-root' && scope.scope ? `${scope.scope}/` : null;
  if (!prefix) return false;
  try {
    if (originKey(recorded) === originKey(prefix + origin)) return sameSyncOrigin(recorded, origin, scope, recordedSlug);
    if (originKey(origin) === originKey(prefix + recorded)) return sameSyncOrigin(origin, recorded, scope, originSlug);
  } catch {
    return true;
  }
  return false;
}

/**
 * Refuses (`page_identity_changed`, detail `origin_already_claimed`) when the target would become a live claimant of an
 * origin another live page of its source records, in any spelling discovery reads as the same file. Runs inside the
 * caller's `engine.transaction()` and holds the origin's advisory lock until it ends, so two writers assigning one origin
 * to different pages serialize and the second sees the first.
 */
export async function assertOriginUnclaimed(tx: BrainEngine, target: OriginTarget): Promise<void> {
  if (!(tx as { _heldPageKeys?: unknown })._heldPageKeys) throw new Error('assertOriginUnclaimed requires engine.transaction(): the origin lock and the write must commit together');
  const [row] = target.pageId != null
    ? await tx.executeRaw<TargetRow>('SELECT id, slug, source_path, deleted_at FROM pages WHERE id=$1 AND source_id=$2', [target.pageId, target.sourceId])
    : target.slug ? await tx.executeRaw<TargetRow>('SELECT id, slug, source_path, deleted_at FROM pages WHERE source_id=$1 AND slug=$2', [target.sourceId, target.slug]) : [];
  const origin = target.sourcePath ?? row?.source_path ?? null;
  if (!origin || row && row.deleted_at != null && !target.revive) return;
  const scope = target.scope === undefined ? await originScopeOf(tx, target.sourceId) : target.scope ?? undefined;
  const slug = row?.slug ?? target.slug;
  if (row && row.deleted_at == null && row.source_path != null && sameOrigin(row.source_path, row.slug, origin, slug, scope)) return;
  const prefix = scope?.slugMode === 'source-root' && scope.scope ? `${scope.scope}/` : null;
  const forms = [origin, ...(prefix ? [prefix + origin] : []), ...(prefix && origin.startsWith(prefix) ? [origin.slice(prefix.length)] : [])];
  const spellings = [...new Set(forms.map(originKey))].sort();
  for (const key of [...new Set(forms.map(lockKey))].sort()) {
    await tx.executeRaw('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [`gbrain:origin:${JSON.stringify([target.sourceId, key])}`]);
  }
  const pathSql = process.platform === 'win32' ? "lower(replace(source_path,chr(92),'/'))=ANY($2::text[])" : 'source_path=ANY($2::text[])';
  const holders = (await tx.executeRaw<{ slug: string; source_path: string }>(
    `SELECT slug, source_path FROM pages WHERE source_id=$1 AND deleted_at IS NULL AND ${pathSql} AND id<>$3 ORDER BY slug`, [target.sourceId, spellings, row?.id ?? -1]))
    .filter(holder => sameOrigin(holder.source_path, holder.slug, origin, slug, scope));
  if (holders.length) throw originAlreadyClaimed(target.sourceId, origin, holders.map(holder => holder.slug), slug);
}

/**
 * Records `sourcePath` as the target page's origin, guarded: the assignment statement every origin-assigning write that
 * is not a page upsert uses. `onlyIfUnset` fills a missing origin only; `liveOnly` never touches a tombstone. A page that
 * records the origin drops an `origin_twin` database-only marker (it gave an origin up to a twin and now has its own file
 * again). Returns the number of rows whose origin changed.
 */
export async function bindOrigin(tx: BrainEngine, target: OriginTarget & { sourcePath: string; onlyIfUnset?: boolean; liveOnly?: boolean }): Promise<number> {
  await assertOriginUnclaimed(tx, target);
  const by = target.pageId != null ? 'id=$2' : 'slug=$2';
  const params = [target.sourceId, target.pageId ?? target.slug, target.sourcePath];
  try {
    const changed = (await tx.executeRaw(`UPDATE pages SET source_path=$3 WHERE source_id=$1 AND ${by} AND ${target.onlyIfUnset ? 'source_path IS NULL' : 'source_path IS DISTINCT FROM $3'}`
      + `${target.liveOnly ? ' AND deleted_at IS NULL' : ''} RETURNING id`, params)).length;
    await tx.executeRaw(`UPDATE pages SET database_only_reason=NULL WHERE source_id=$1 AND ${by} AND source_path=$3 AND database_only_reason='origin_twin'`, params);
    return changed;
  } catch (error) {
    throw classifyOriginUniqueViolation(error, target) ?? error;
  }
}

/** Every soft-deleted page `restorePage(slug, opts)` would revive, guarded (a restore without a source revives the slug in every source). */
export async function assertRevivalUnclaimed(tx: BrainEngine, slug: string, sourceId?: string): Promise<void> {
  const rows = await tx.executeRaw<{ id: number; source_id: string }>(
    'SELECT id, source_id FROM pages WHERE slug=$1 AND deleted_at IS NOT NULL AND ($2::text IS NULL OR source_id=$2) ORDER BY source_id', [slug, sourceId ?? null]);
  for (const row of rows) await assertOriginUnclaimed(tx, { sourceId: row.source_id, pageId: Number(row.id), revive: true });
}

/**
 * Of the live pages recording one origin, the one a reader or a repair may act on: the only one, else the one whose slug
 * is the file's derived slug (`resolveSlugForPath`); several with none canonical are `{ ambiguous }` (never written into).
 */
export function pickCanonicalOrigin<T extends { slug: string }>(pages: readonly T[], sourcePath: string): T | { ambiguous: string[] } | null {
  if (pages.length <= 1) return pages[0] ?? null;
  const derived = resolveSlugForPath(sourcePath);
  const canonical = pages.filter(page => page.slug === derived);
  return canonical.length === 1 ? canonical[0]! : { ambiguous: pages.map(page => page.slug).sort() };
}

export async function canonicalOriginPage(engine: Exec, sourceId: string, sourcePath: string): Promise<{ id: number; slug: string } | { ambiguous: string[] } | null> {
  const rows = await engine.executeRaw<{ id: number; slug: string }>(
    'SELECT id, slug FROM pages WHERE source_id=$1 AND source_path=$2 AND deleted_at IS NULL ORDER BY slug', [sourceId, sourcePath]);
  return pickCanonicalOrigin(rows.map(row => ({ id: Number(row.id), slug: row.slug })), sourcePath);
}