Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.7 KB
Raw Blame
import { randomUUID } from 'node:crypto';
import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
import { join } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import type { SqlEngine } from './model.ts';
import { repairWedgedReservation, resolveCoordinationLock } from './coordination-lock.ts';
import { canonicalFilesystemPath } from './root-registry.ts';
import type { OperationError } from '../ops/contract.ts';
import { adoptTransferredRootStamp, assertNoPhysicalRootOverlap, assertPhysicalRoot, assertPhysicalRootStamp, describeMovedPhysicalRoot, PHYSICAL_ROOT_MARKER, physicalRootDeviceChange, physicalRootError,
  physicalRootMovedError, physicalRootMovedRefusal, readPhysicalRootReservation, readPhysicalRootStamp, reservePhysicalRootRecord, restampPhysicalRootDevice, samePhysicalBirth, writePhysicalRootStamp,
  type MovedPhysicalRoot, type PhysicalRootReservation } from './physical-root-record.ts';

export { assertPhysicalRoot, isPhysicalRootMetadata, readPhysicalRootReservation } from './physical-root-record.ts';
export interface PhysicalRootClaim { hostId: string; worktreeId?: string; coordinationPath?: string; }
async function brainIdentity(tx: SqlEngine): Promise<string> {
  const [brain] = await tx.executeRaw<{ brain_id: string }>('SELECT brain_id FROM persistence_brain WHERE singleton=1');
  if (!brain) throw physicalRootError();
  return brain.brain_id;
}
/**
 * Caller holds the brain/topology transaction guard. The private shared-path
 * reservation is a veto, never database ownership authority. It is deliberately
 * retained after a transaction rollback or process death.
 */
export async function reservePhysicalRoot(tx: SqlEngine, path: string, opts: PhysicalRootClaim): Promise<PhysicalRootReservation> {
  const root = canonicalFilesystemPath(path), brainId = await brainIdentity(tx);
  await repairWedgedReservation(tx, root, opts.hostId);
  const previous = readPhysicalRootReservation(root);
  const worktreeId = opts.worktreeId ?? previous?.worktreeId ?? randomUUID();
  const coordinationPath = opts.coordinationPath ?? resolveCoordinationLock(root, worktreeId, { reservation: previous?.coordinationPath }, opts.hostId).path;
  // A copied marker without its original sibling reservation is not a new root; a moved checkout is named, path-free (#8625).
  if (!previous && existsSync(join(root, PHYSICAL_ROOT_MARKER))) throw await movedPhysicalRoot(tx, root, opts.hostId) ? physicalRootMovedError() : physicalRootError();
  const reservation = previous ?? reservePhysicalRootRecord(root, { brainId, worktreeId, hostId: opts.hostId, coordinationPath });
  if (reservation.brainId !== brainId || reservation.worktreeId !== worktreeId || reservation.coordinationPath !== coordinationPath) throw physicalRootError();
  const [owner] = await tx.executeRaw<{ owner_host_id: string | null }>('SELECT owner_host_id FROM persistence_worktrees WHERE id=$1::uuid', [worktreeId]);
  if (owner ? owner.owner_host_id !== opts.hostId : reservation.hostId !== opts.hostId) throw physicalRootError('Another host owns or has prepared this physical checkout.');
  assertNoPhysicalRootOverlap(root);
  return reservation;
}
/**
 * #8625: the file evidence of a moved checkout at `path`, accepted only when this brain recorded it: the stamp's brain,
 * its worktree owned by `hostId`, and that worktree's host binding still at the recorded root. Read-only.
 */
export async function movedPhysicalRoot(tx: SqlEngine, path: string, hostId: string | null):
  Promise<(MovedPhysicalRoot & { members: Array<{ sourceId: string; relativePath: string }> }) | null> {
  const moved = describeMovedPhysicalRoot(canonicalFilesystemPath(path));
  if (!moved || !hostId) return null;
  const [row] = await tx.executeRaw<{ brain_id: string; owner_host_id: string | null; local_path: string | null }>(`SELECT brain_id::text AS brain_id,
    (SELECT owner_host_id::text FROM persistence_worktrees WHERE id=$1::uuid) AS owner_host_id,
    (SELECT local_path FROM persistence_host_bindings WHERE worktree_id=$1::uuid AND host_id=$2::uuid) AS local_path
    FROM persistence_brain WHERE singleton=1`, [moved.worktreeId, hostId]);
  if (row?.brain_id !== moved.brainId || row.owner_host_id !== hostId || row.local_path !== moved.recorded) return null;
  const members = await tx.executeRaw<{ source_id: string; relative_path: string }>(
    'SELECT source_id,relative_path FROM persistence_source_bindings WHERE worktree_id=$1::uuid ORDER BY source_id', [moved.worktreeId]);
  return { ...moved, members: members.map(member => ({ sourceId: member.source_id, relativePath: member.relative_path })) };
}
/** #8625: the full moved-checkout refusal for a trusted local caller (paths, worktree, exit); null when `root` is no moved checkout of this host, or not of `recorded`. */
export async function movedPhysicalRootRefusal(tx: SqlEngine, root: string, exit: { sourceId: string; operation: 'add' | 'claim' | 'rebind' }, hostId: string | null,
  recorded?: string): Promise<OperationError | null> {
  const moved = await movedPhysicalRoot(tx, root, hostId);
  if (!moved || recorded !== undefined && moved.recorded !== recorded) return null;
  return physicalRootMovedRefusal(moved, { ...exit, members: moved.members });
}
/** Existing bindings require their stamp; only a never-committed original claim may finish creating it. */
export async function claimPhysicalRoot(tx: SqlEngine, path: string, opts: PhysicalRootClaim): Promise<PhysicalRootReservation> {
  const reservation = await reservePhysicalRoot(tx, path, opts);
  const [owner] = await tx.executeRaw<{ state: string }>('SELECT state FROM persistence_worktrees WHERE id=$1::uuid', [reservation.worktreeId]);
  if (owner && owner.state !== 'active') throw physicalRootError('Finish the prepared transfer or recovery before claiming this root.');
  const [bound] = await tx.executeRaw<{ local_path: string; coordination_path: string }>('SELECT local_path,coordination_path FROM persistence_host_bindings WHERE worktree_id=$1::uuid AND host_id=$2::uuid', [reservation.worktreeId, opts.hostId]);
  if (bound) {
    if (bound.local_path !== reservation.root || bound.coordination_path !== reservation.coordinationPath) throw physicalRootError('This worktree was rebound to a different checkout.');
    assertPhysicalRoot(reservation.root, reservation);
  }
  else {
    const info = statSync(reservation.root, { bigint: true });
    if (reservation.initialDevice !== info.dev.toString() || reservation.initialInode !== info.ino.toString() || !samePhysicalBirth(reservation.initialBirth, info.birthtimeNs)) throw physicalRootError();
    writePhysicalRootStamp(reservation.root, reservation);
  }
  return reservation;
}
/**
 * Only durable directory-swap recovery may stamp a different inode. The caller
 * has verified the canonical manifest and holds the stable outside-root lock.
 * Moving this stage to target preserves the stamp and immutable reservation.
 */
export async function preparePhysicalRootReplacement(tx: SqlEngine, stage: string, target: string,
  opts: Required<PhysicalRootClaim>): Promise<void> {
  const reservation = await reservePhysicalRoot(tx, target, opts);
  const [owner] = await tx.executeRaw<{ owner_host_id: string; state: string }>('SELECT owner_host_id,state FROM persistence_worktrees WHERE id=$1::uuid', [opts.worktreeId]);
  if (owner?.owner_host_id !== opts.hostId || owner.state !== 'recovering') throw physicalRootError('A directory replacement requires durable source recovery.');
  if (existsSync(target)) assertPhysicalRoot(target, opts);
  writePhysicalRootStamp(stage, reservation);
  assertPhysicalRootStamp(stage, reservation);
}
/** Called only after the draining epoch and complete successor manifest were verified under SQL/native guards. */
export async function preparePhysicalRootTransfer(tx: SqlEngine, path: string,
  opts: Required<PhysicalRootClaim> & { expectedEpoch: string }): Promise<void> {
  const [owner] = await tx.executeRaw<{ owner_epoch: string; state: string }>('SELECT owner_epoch,state FROM persistence_worktrees WHERE id=$1::uuid', [opts.worktreeId]);
  if (owner?.state !== 'draining' || String(owner.owner_epoch) !== opts.expectedEpoch) throw physicalRootError();
  const root = canonicalFilesystemPath(path), brainId = await brainIdentity(tx);
  const reservation = readPhysicalRootReservation(root) ?? reservePhysicalRootRecord(root,
    { brainId, worktreeId: opts.worktreeId, hostId: opts.hostId, coordinationPath: opts.coordinationPath });
  if (reservation.brainId !== brainId || reservation.worktreeId !== opts.worktreeId || reservation.coordinationPath !== opts.coordinationPath) throw physicalRootError();
  assertNoPhysicalRootOverlap(root);
  adoptTransferredRootStamp(root, reservation);
}

type DeviceChange = { from: string; to: string };
function restampRecovery(recovery: Record<string, any> | undefined, change: DeviceChange): boolean {
  let changed = false;
  for (const [record, field] of [[recovery?.before?.reservation, 'initialDevice'], [recovery?.before?.stamp, 'device'],
    [recovery?.reservation, 'initialDevice'], [recovery?.stamp, 'device']] as const) {
    if (record?.[field] === change.from) { record[field] = change.to; changed = true; }
  }
  return changed;
}
/**
 * #5604: re-stamp every persisted device copy (ownership stamp, reservation,
 * recorded self-transfer and retained topology staging identity) when only the
 * filesystem device id changed. The caller holds the outside-root native lock;
 * database ownership is verified in the same transaction that rewrites the
 * database copies, and the files are rewritten after it commits.
 */
export async function restampPhysicalRoot(engine: BrainEngine, binding: { worktree_id: string; local_path: string | null; coordination_path: string | null },
  hostId: string): Promise<DeviceChange | null> {
  const root = binding.local_path;
  if (!root || !binding.coordination_path || realpathSync(root) !== root || lstatSync(root).isSymbolicLink()) return null;
  const reservation = readPhysicalRootReservation(root), stamp = readPhysicalRootStamp(root);
  if (!reservation || !stamp || reservation.worktreeId !== binding.worktree_id || reservation.coordinationPath !== binding.coordination_path) return null;
  const change = physicalRootDeviceChange(stamp, reservation, statSync(root, { bigint: true }));
  if (!change) return null;
  const applied = await engine.transaction(async tx => {
    await tx.executeRaw("SELECT set_config('synchronous_commit','on',true)");
    const [owner] = await tx.executeRaw<{ owner_host_id: string | null; manifest: Record<string, any> | null }>(
      'SELECT owner_host_id,manifest FROM persistence_worktrees WHERE id=$1::uuid FOR UPDATE', [binding.worktree_id]);
    const [brain] = await tx.executeRaw<{ brain_id: string }>('SELECT brain_id FROM persistence_brain WHERE singleton=1');
    const [bound] = await tx.executeRaw<{ local_path: string; coordination_path: string }>(
      'SELECT local_path,coordination_path FROM persistence_host_bindings WHERE worktree_id=$1::uuid AND host_id=$2::uuid', [binding.worktree_id, hostId]);
    if (!owner || owner.owner_host_id !== hostId || brain?.brain_id !== stamp.brainId
      || bound?.local_path !== root || bound.coordination_path !== binding.coordination_path) return false;
    const manifest = owner.manifest;
    if (manifest && restampRecovery(manifest.self_transfer, change)) {
      await tx.executeRaw('UPDATE persistence_worktrees SET manifest=$2::text::jsonb WHERE id=$1::uuid', [binding.worktree_id, JSON.stringify(manifest)]);
    }
    const topology = await tx.executeRaw<{ id: string; recovery: Record<string, any> | null }>(
      "SELECT id,recovery FROM persistence_topology_changes WHERE state='recovering' AND $1::uuid=ANY(worktree_ids) FOR UPDATE", [binding.worktree_id]);
    for (const row of topology) {
      const identity = row.recovery?.stageIdentity, stage = row.recovery?.stage;
      if (identity?.device !== change.from || typeof stage !== 'string' || !existsSync(stage)) continue;
      const info = lstatSync(stage, { bigint: true });
      if (!info.isDirectory() || info.ino.toString() !== identity.inode || info.birthtimeNs.toString() !== identity.birthNs || info.dev.toString() !== change.to) continue;
      identity.device = change.to;
      await tx.executeRaw('UPDATE persistence_topology_changes SET recovery=$2::text::jsonb,updated_at=now() WHERE id=$1::uuid', [row.id, JSON.stringify(row.recovery)]);
    }
    return true;
  });
  if (!applied) return null;
  // Database copies commit first; each update is conditional on the old device, so
  // a crash before the files are rewritten leaves a device-only change that the next
  // locked acquisition re-stamps again.
  restampPhysicalRootDevice(root, reservation, stamp, change);
  process.stderr.write(`[persistence] physical root ${root} filesystem device id changed ${change.from} -> ${change.to}; inode, birth time and owner token matched, so every persisted copy was re-stamped.\n`);
  return change;
}