Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.8 KB
Raw Blame
import type { BrainEngine } from '../engine.ts';
import { validateSlug } from '../utils.ts';
import type { PageKey } from './types.ts';
import { pipelined } from './transactions.ts';

/** A missing source refuses every write; bulk derived work may defer that origin. */
export class PageSourceMissingError extends Error {
  constructor(readonly sourceId: string) {
    super(`Page source does not exist: ${sourceId}`);
    this.name = 'PageSourceMissingError';
  }
}

/**
 * Source locks precede auth/request locks in callers; repeat held locks safely.
 * #5984: the guard statements are pipelined in the sorted key order. Keys that
 * all carry their source's expected `incarnation` send the source reads in the
 * same pipeline; a source that is missing or was recreated then fails the call
 * after its statements ran, so the caller's transaction must roll back.
 */
export async function lockPageKeys(engine: Pick<BrainEngine, 'executeRaw'> & { kind?: string }, keys: readonly PageKey[]): Promise<void> {
  const unique = new Map<string, PageKey>();
  for (const key of keys) {
    if (!key.sourceId) throw new TypeError('A page guard requires an exact sourceId');
    const slug = validateSlug(key.slug);
    unique.set(JSON.stringify([key.sourceId, slug]), { sourceId: key.sourceId, slug, ...(key.incarnation ? { incarnation: key.incarnation } : {}) });
  }
  const ordered = [...unique.values()].sort((a, b) => a.sourceId < b.sourceId ? -1 : a.sourceId > b.sourceId ? 1 : a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0);
  const expected = new Map<string, string>();
  for (const { sourceId, incarnation } of ordered) if (incarnation && (expected.get(sourceId) ?? incarnation) === incarnation) expected.set(sourceId, incarnation);
  const hinted = ordered.every(key => key.incarnation && expected.get(key.sourceId) === key.incarnation);
  const readSource = (sourceId: string) => engine.executeRaw<{ incarnation: string }>('SELECT incarnation FROM sources WHERE id=$1 FOR SHARE', [sourceId]).then(rows => {
    if (!rows.length) throw new PageSourceMissingError(sourceId);
    if (hinted && rows[0]!.incarnation !== expected.get(sourceId)) throw new Error(`Page source was recreated: ${sourceId}`);
    return rows[0]!.incarnation;
  });
  // One unhinted key (the common single write): its share lock and the guard statements are sent together;
  // the guards take the incarnation from the locked row, and a missing source is reported before anything else.
  if (!hinted && ordered.length === 1) {
    const key = ordered[0]!;
    await pipelined({ kind: engine.kind ?? '' }, [
      async () => {
        const rows = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation FROM sources WHERE id=$1 FOR SHARE', [key.sourceId]);
        if (!rows.length) throw new PageSourceMissingError(key.sourceId);
      },
      () => engine.executeRaw('INSERT INTO page_write_guards(source_incarnation,slug) SELECT incarnation,$2 FROM sources WHERE id=$1 ON CONFLICT DO NOTHING', [key.sourceId, key.slug]),
      () => engine.executeRaw('SELECT g.slug FROM page_write_guards g JOIN sources s ON s.incarnation=g.source_incarnation WHERE s.id=$1 AND g.slug=$2 FOR UPDATE OF g', [key.sourceId, key.slug]),
      // Also fence direct SQL row writers. The guard remains when this row is absent.
      () => engine.executeRaw('SELECT id FROM pages WHERE source_id=$1 AND slug=$2 FOR UPDATE', [key.sourceId, key.slug]),
    ]);
    return;
  }
  const run = (calls: Array<() => Promise<unknown>>) => pipelined({ kind: engine.kind ?? '' }, calls);
  const sources = new Map<string, string>(hinted ? expected : []);
  const reads: Array<() => Promise<unknown>> = [];
  for (const sourceId of new Set(ordered.map(key => key.sourceId))) {
    if (hinted) reads.push(() => readSource(sourceId));
    else sources.set(sourceId, await readSource(sourceId));
  }
  if (ordered.length > 1) {
    // #5984: many keys in three statements, still created and locked in the sorted key order.
    const incarnations = ordered.map(key => sources.get(key.sourceId)!), slugs = ordered.map(key => key.slug), sourceIds = ordered.map(key => key.sourceId);
    await run([...reads,
      () => engine.executeRaw('INSERT INTO page_write_guards(source_incarnation,slug) SELECT i,s FROM unnest($1::uuid[],$2::text[]) WITH ORDINALITY AS k(i,s,n) ORDER BY n ON CONFLICT DO NOTHING', [incarnations, slugs]),
      () => engine.executeRaw(`SELECT g.slug FROM unnest($1::uuid[],$2::text[]) WITH ORDINALITY AS k(i,s,n)
      JOIN page_write_guards g ON g.source_incarnation=k.i AND g.slug=k.s ORDER BY k.n FOR UPDATE OF g`, [incarnations, slugs]),
      () => engine.executeRaw(`SELECT p.id FROM unnest($1::text[],$2::text[]) WITH ORDINALITY AS k(src,s,n)
      JOIN pages p ON p.source_id=k.src AND p.slug=k.s ORDER BY k.n FOR UPDATE OF p`, [sourceIds, slugs]),
    ]);
    return;
  }
  await run([...reads, ...ordered.flatMap(key => {
    const params = [sources.get(key.sourceId)!, key.slug];
    return [
      () => engine.executeRaw('INSERT INTO page_write_guards(source_incarnation,slug) VALUES ($1::uuid,$2) ON CONFLICT DO NOTHING', params),
      () => engine.executeRaw('SELECT slug FROM page_write_guards WHERE source_incarnation=$1::uuid AND slug=$2 FOR UPDATE', params),
      // Also fence direct SQL row writers. The guard remains when this row is absent.
      () => engine.executeRaw('SELECT id FROM pages WHERE source_id=$1 AND slug=$2 FOR UPDATE', [key.sourceId, key.slug]),
    ];
  })]);
}

/**
 * Guards a transaction already holds, chained through its open savepoints.
 * The transaction's session owns them until the transaction or savepoint
 * ends, so they are not re-acquired. That includes a key whose pages row was
 * absent when it was locked: the only pages INSERT (engine-sql/pages.ts
 * putPage) runs after both engines' putPage take the same guard.
 */
export interface HeldPageKeys { keys: Set<string>; parent: HeldPageKeys | null }
function pageGuardKey(key: PageKey): string | null {
  if (!key.sourceId) return null;
  try { return JSON.stringify([key.sourceId, validateSlug(key.slug)]); } catch { return null; }
}
function holds(held: HeldPageKeys | null, id: string): boolean {
  for (; held; held = held.parent) if (held.keys.has(id)) return true;
  return false;
}
/**
 * Fails closed unless `engine` is a transaction that already holds every key
 * (the belief ledger's finalization contract, docs/designs/BELIEF_LEDGER.md
 * section 5.3). It never takes a lock: one taken late, outside lockPageKeys'
 * sorted acquisition, can deadlock.
 */
export function assertHeldPageKeys(engine: object, keys: readonly PageKey[]): void {
  const held = (engine as { _heldPageKeys?: HeldPageKeys | null })._heldPageKeys ?? null;
  const missing = keys.filter(key => { const id = pageGuardKey(key); return id === null || !holds(held, id); });
  if (missing.length) {
    throw Object.assign(new Error(`belief ledger append requires held page keys: ${missing.map(k => `${k.sourceId}/${k.slug}`).join(', ')}`), { code: 'belief_page_key_not_held' });
  }
}

/** lockPageKeys for keys this transaction does not hold yet; invalid keys still reach its checks. */
export async function lockUnheldPageKeys(engine: Pick<BrainEngine, 'executeRaw'> & { kind?: string }, held: HeldPageKeys, keys: readonly PageKey[]): Promise<void> {
  const pending = keys.filter(key => { const id = pageGuardKey(key); return id === null || !holds(held, id); });
  if (!pending.length) return;
  await lockPageKeys(engine, pending);
  for (const key of pending) held.keys.add(pageGuardKey(key)!);
}
/** Runs a transaction or savepoint; a released savepoint's guards stay held by its parent, a rolled-back one's do not. */
export async function withHeldPageKeys<T>(parent: HeldPageKeys | null, run: (held: HeldPageKeys) => Promise<T>): Promise<T> {
  const held: HeldPageKeys = { keys: new Set(), parent };
  const result = await run(held);
  for (const key of held.keys) parent?.keys.add(key);
  return result;
}