Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.8 KB
Raw Blame
import type { SqlEngine, WriteRequest } from './model.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { readPersistenceBrain } from './managed-mode.ts';

const declared = new WeakSet<object>();
/**
 * Global persistence lock order: the `persistence_brain` row, then worktree
 * rows (id order), then source rows (id order), then counters, requests and
 * page keys. The request and effect protocol triggers read the brain row
 * FOR SHARE, and worktree claims and topology changes lock it FOR UPDATE
 * before their worktrees, sources and counters. A transaction that locked a
 * source or counter row before its first request or effect write would wait
 * for the brain row while holding what the topology change waits for, so
 * every protocol declaration takes the brain row FOR SHARE first, in the same
 * statement as its settings (a missing row still declares). Declare before
 * any other row lock. A transaction needing the exclusive brain lock takes it
 * first and declares after it.
 */
const BRAIN_SHARE = '(SELECT brain_id::text FROM persistence_brain WHERE singleton=1 FOR SHARE) AS brain';

/** Transaction-local; #5984: a transaction engine declares it once (a savepoint is its own engine object). */
export async function declarePersistenceProtocol(tx: SqlEngine): Promise<void> {
  const inTransaction = (tx as { _pageTransaction?: boolean })._pageTransaction === true;
  if (inTransaction && declared.has(tx)) return;
  await tx.executeRaw(`SELECT set_config('gbrain.persistence_protocol','2',true),${BRAIN_SHARE}`);
  if (inTransaction) declared.add(tx);
}

/**
 * #6007: the protocol declaration plus the durable-write settings (synchronous
 * commit, lock and statement timeouts) in one round trip, then the brain row
 * under that lock timeout. Later `declarePersistenceProtocol` calls on the
 * same transaction engine are free.
 */
/**
 * Returns the brain id read under that lock (null when the row is missing). `idleInTransaction` also sets a
 * transaction-local idle bound in the same statement, first (a publication's, publication-deadline.ts).
 */
export async function declareDurablePersistence(tx: SqlEngine, lockTimeout = '1s', statementTimeout = '5s', idleInTransaction?: string): Promise<string | null> {
  const idle = idleInTransaction === undefined ? '' : "set_config('idle_in_transaction_session_timeout',$3,true),";
  const [row] = await tx.executeRaw<{ brain: string | null }>(`SELECT ${idle}set_config('gbrain.persistence_protocol','2',true),set_config('synchronous_commit','on',true),
    set_config('lock_timeout',$1,true),set_config('statement_timeout',$2,true),${BRAIN_SHARE}`,
    idleInTransaction === undefined ? [lockTimeout, statementTimeout] : [lockTimeout, statementTimeout, idleInTransaction]);
  if ((tx as { _pageTransaction?: boolean })._pageTransaction === true) declared.add(tx);
  return row?.brain ?? null;
}

const LOCAL_SETTING = String.raw`set_config\('[a-z_.]+',(?:\$\d+|'[^']*'),true\)`;
const DECLARATION = new RegExp(`^SELECT ${LOCAL_SETTING}(?:,\\s*${LOCAL_SETTING})*(?:,\\s*${BRAIN_SHARE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})?$`);
/**
 * GBRA-156: whether `statement` is a declaration this module sends: one SELECT of transaction-local set_config calls,
 * optionally with the brain row FOR SHARE. Run outside a transaction it changes nothing (a local setting ends with its
 * statement, and so does the share lock), so a transaction whose first statement it is may send it before BEGIN's
 * answer (`TransactionOptions.pipelineFirst`): if BEGIN fails, only this statement runs, in autocommit. It accepts no
 * other text, writes included, and nothing containing `;` (a simple-protocol query may hold several statements).
 */
export function isPersistenceDeclaration(statement: string): boolean {
  return !statement.includes(';') && DECLARATION.test(statement.trim());
}

export const PERSISTENCE_PROTOCOL_PREDICATE = "set_config('gbrain.persistence_protocol','2',true)='2'";

export function assertMutationProtocol(row: Pick<WriteRequest, 'target_kind' | 'protocol_version'>): void {
  if (((row.target_kind ?? 'page') === 'page' && (row.protocol_version ?? 1) === 1)
    || (row.target_kind === 'skill_bundle' && row.protocol_version === 2)) return;
  throw opError('unsupported_mutation_protocol', 'This consumer does not support the request target and protocol version.',
    `This gbrain process cannot apply ${row.target_kind ?? 'page'} requests at protocol ${row.protocol_version ?? 1}, so it left the request untouched. A newer gbrain wrote it: upgrading gbrain on this host (the user's call) lets it be applied.`);
}

export async function assertSharedSkillPersistence(engine: SqlEngine, sourceId?: string): Promise<void> {
  const brain = await readPersistenceBrain(engine);
  if (!brain.enabled || !brain.skill_bundles_enabled || brain.writer_protocol_floor !== 2) {
    throw new OperationError('writer_not_quiesced', 'Shared skill publication requires an activated protocol-2 canonical owner.',
      'Stop older writers and direct-file skill servers, then activate shared skill persistence on the canonical host.');
  }
  if (sourceId !== undefined) {
    const owners = await engine.executeRaw(`SELECT w.id FROM sources s JOIN persistence_source_bindings b
      ON b.source_id=s.id AND b.source_incarnation=s.incarnation JOIN persistence_worktrees w ON w.id=b.worktree_id
      JOIN persistence_writer_protocols p ON p.worktree_id=w.id AND p.host_id=w.owner_host_id AND p.owner_epoch=w.owner_epoch
      WHERE s.id=$1 AND NOT s.archived AND w.state='active' AND p.protocol_version=2`, [sourceId]);
    if (!owners.length) throw new OperationError('writer_not_quiesced', 'The canonical owner capability changed after shared publication was activated.',
      'Drain or cancel pending requests and revalidate the canonical owner before activating shared publication again.');
  }
}