Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.4 KB
Raw Blame
/**
 * #6712 PR 4b (design v3.2 §8): `sync.admission`, the brain-wide switch that pauses what a managed pass admits.
 *
 * - `normal` (the default): the pass admits everything it classifies.
 * - `imports_only`: no deletes and no keep_db writes; those paths settle as `paused_deletes` / `paused_keep_db`.
 * - `classify_only`: the pass reads and classifies, writes telemetry only, and stamps nothing (stop `admission_paused`).
 *
 * The value is read at pin, inside every group's admission transaction, and by the destructive kinds at publication, so
 * a change takes effect at the next group. An unrecognized stored value reads as `classify_only` (fail closed).
 *
 * `set_at`: the config table has no timestamp, so local `gbrain config set` (`writeSyncAdmission`) records the value
 * and the database's clock in an `op_checkpoints` row (`op='sync-admission'`, fingerprint `brain`) in the same
 * transaction as the config row. The row dates the stored value only while it names that value: a value written any
 * other way (or a row the checkpoint GC dropped) reads `set_at: null`. `syncAdmissionStatus` turns `effective` once
 * no pass pinned before `set_at` holds the lease and no destructive request admitted before it is unpublished; with
 * `set_at` unknown, every open pass and every unpublished destructive request counts as earlier.
 */
import type { BrainEngine } from '../engine.ts';
import { syncLockId } from '../db-lock.ts';
import { MANAGED_SYNC_PASS_OP, passFingerprint } from './sync-pass-row.ts';

export const SYNC_ADMISSION_KEY = 'sync.admission';
export const SYNC_ADMISSION_VALUES = ['normal', 'imports_only', 'classify_only'] as const;
export type SyncAdmission = typeof SYNC_ADMISSION_VALUES[number];

export function parseSyncAdmission(value: string | null | undefined): SyncAdmission {
  const trimmed = value?.trim();
  if (!trimmed) return 'normal';
  return (SYNC_ADMISSION_VALUES as readonly string[]).includes(trimmed) ? trimmed as SyncAdmission : 'classify_only';
}

/** The value in effect, read in the caller's transaction (`tx`) when given, so admission and publication see one value. */
export async function readSyncAdmission(engine: Pick<BrainEngine, 'executeRaw'>): Promise<SyncAdmission> {
  const [row] = await engine.executeRaw<{ value: string | null }>('SELECT value FROM config WHERE key=$1', [SYNC_ADMISSION_KEY]);
  return parseSyncAdmission(row?.value ?? null);
}

/** Whether a kind of write may be admitted (or published) under `admission`. */
export function admissionAllows(admission: SyncAdmission, kind: 'import' | 'destructive'): boolean {
  if (admission === 'normal') return true;
  return admission === 'imports_only' && kind === 'import';
}

/** The `op_checkpoints` row that dates the stored value (see the module comment). */
export const SYNC_ADMISSION_SET_OP = 'sync-admission';
const SET_FINGERPRINT = 'brain';
/** The destructive request kinds (design §8): a managed delete, and the DB-wins reconcile keep_db admits. */
export const SYNC_ADMISSION_DESTRUCTIVE_KINDS = ['managed_sync_delete', 'canonical_reconcile'] as const;

type Exec = Pick<BrainEngine, 'executeRaw'>;
const iso = (value: Date | string | null | undefined) => value == null ? null : new Date(value).toISOString();

export interface SyncAdmissionSetting {
  /** The value in effect (`parseSyncAdmission` of the stored one). */
  value: SyncAdmission;
  /** The stored config value, verbatim (null when unset). */
  stored: string | null;
  /** When local `config set` wrote the stored value (database clock), or null when unknown or unset. */
  set_at: string | null;
}

export interface SyncAdmissionStatus { value: SyncAdmission; set_at: string | null; effective: boolean }

/** The value in effect, the stored value and its `set_at`, in one read. */
export async function readSyncAdmissionSetting(engine: Exec): Promise<SyncAdmissionSetting> {
  const { raw_set_at, ...setting } = await readSetting(engine);
  return { ...setting, set_at: iso(raw_set_at) };
}

/** The raw setting row: the stored config value and the dating row's value and `set_at`. */
export interface SyncAdmissionSettingRow { stored: string | null; row_value: string | null; set_at: string | null }

/**
 * The setting's columns and joins for a read that folds it in (`sync status` rides its source read, keeping its statement
 * budget): `$k`..`$k+2` bind `SYNC_ADMISSION_SETTING_PARAMS`, and the columns are `admission_stored`, `admission_row_value`
 * and `admission_set_at`.
 */
export const syncAdmissionSettingSql = (k: number) => ({
  columns: `ac.value AS admission_stored, ao.completed_keys->0->>'value' AS admission_row_value, ao.completed_keys->0->>'set_at' AS admission_set_at`,
  joins: `LEFT JOIN config ac ON ac.key=$${k} LEFT JOIN op_checkpoints ao ON ao.op=$${k + 1} AND ao.fingerprint=$${k + 2}` });
export const SYNC_ADMISSION_SETTING_PARAMS = [SYNC_ADMISSION_KEY, SYNC_ADMISSION_SET_OP, SET_FINGERPRINT];

async function readSetting(engine: Exec): Promise<Omit<SyncAdmissionSetting, 'set_at'> & { raw_set_at: string | null }> {
  const [row] = await engine.executeRaw<SyncAdmissionSettingRow>(
    `SELECT c.value AS stored, o.completed_keys->0->>'value' AS row_value, o.completed_keys->0->>'set_at' AS set_at
       FROM (SELECT 1) one LEFT JOIN config c ON c.key=$1 LEFT JOIN op_checkpoints o ON o.op=$2 AND o.fingerprint=$3`,
    SYNC_ADMISSION_SETTING_PARAMS);
  return settingOf(row);
}
function settingOf(row: SyncAdmissionSettingRow | undefined): Omit<SyncAdmissionSetting, 'set_at'> & { raw_set_at: string | null } {
  const stored = row?.stored ?? null;
  return { value: parseSyncAdmission(stored), stored, raw_set_at: stored !== null && row?.row_value === stored ? row.set_at : null };
}

/** Stores `value` and its `set_at` (database clock) in one transaction; returns `set_at`. The caller validated `value`. */
export async function writeSyncAdmission(engine: Pick<BrainEngine, 'transaction'>, value: SyncAdmission): Promise<string> {
  return engine.transaction(async tx => {
    await tx.setConfig(SYNC_ADMISSION_KEY, value);
    const [row] = await tx.executeRaw<{ set_at: string }>(`INSERT INTO op_checkpoints(op,fingerprint,completed_keys,updated_at)
      VALUES($1,$2,jsonb_build_array(jsonb_build_object('value',$3::text,'set_at',clock_timestamp())),now())
      ON CONFLICT (op,fingerprint) DO UPDATE SET completed_keys=EXCLUDED.completed_keys, updated_at=now()
      RETURNING completed_keys->0->>'set_at' AS set_at`, [SYNC_ADMISSION_SET_OP, SET_FINGERPRINT, value]);
    return iso(row!.set_at)!;
  });
}

/** `effective`'s two probes as SQL: `e` names the expressions they read (binds, or columns of an enclosing read). */
function effectProbes(e: { lock: string; passOp: string; passKey: string; setAt: string; sourceId: string; incarnation: string; kinds: string }) {
  return {
    pinned: `EXISTS (SELECT 1 FROM op_checkpoints p JOIN gbrain_cycle_locks l ON l.id=${e.lock} AND l.ttl_expires_at > now()
          AND l.acquisition_token::text = p.completed_keys->0->>'lease_token'
        WHERE p.op=${e.passOp} AND p.fingerprint=${e.passKey} AND p.completed_keys->0->'telemetry'->>'outcome'='open'
          AND (${e.setAt} IS NULL OR (p.completed_keys->0->'telemetry'->>'started_at')::timestamptz < ${e.setAt}))`,
    destructive: `EXISTS (SELECT 1 FROM persistence_requests r WHERE r.source_id=${e.sourceId} AND r.source_incarnation=${e.incarnation}
          AND r.state IN ('queued','running','recovering') AND r.intent->>'kind' = ANY(${e.kinds})
          AND (${e.setAt} IS NULL OR r.created_at < ${e.setAt}))`,
  };
}

/**
 * GBRA-135: `effective`'s probes folded into a read that joins the setting (`syncAdmissionSettingSql`) and the source row
 * `src`, as columns `admission_pinned` and `admission_destructive`: `sync status` reads them with its source, so a
 * restricted value costs it no statement of its own. `$k`..`$k+2` bind `syncAdmissionEffectParams`. Both are null while
 * the stored value reads as `normal` (the guard trims less than `parseSyncAdmission`, so any other value is probed).
 */
export function syncAdmissionEffectSql(k: number, src: string): string {
  const setAt = "(CASE WHEN ao.completed_keys->0->>'value' = ac.value THEN (ao.completed_keys->0->>'set_at')::timestamptz END)";
  const probes = effectProbes({ lock: `$${k}`, kinds: `$${k + 1}::text[]`, passOp: `$${k + 2}`, passKey: `${src}.id||':'||${src}.incarnation::text`, setAt,
    sourceId: `${src}.id`, incarnation: `${src}.incarnation` });
  const restricted = "COALESCE(btrim(ac.value), '') NOT IN ('', 'normal')";
  return `CASE WHEN ${restricted} THEN ${probes.pinned} END AS admission_pinned, CASE WHEN ${restricted} THEN ${probes.destructive} END AS admission_destructive`;
}
export const syncAdmissionEffectParams = (sourceId: string) => [syncLockId(sourceId), [...SYNC_ADMISSION_DESTRUCTIVE_KINDS], MANAGED_SYNC_PASS_OP];

/** A setting row with `effective`'s probes read beside it (`syncAdmissionEffectSql`). */
export interface SyncAdmissionEffectRow extends SyncAdmissionSettingRow { pinned: boolean | null; destructive: boolean | null }

/**
 * `sync status`'s `admission` of one source incarnation (design §8). `effective` is always true for `normal`; otherwise
 * it is false while the source's pass row is `open` with `started_at` before `set_at` and its `lease_token` holds the
 * live drain lease, or while a destructive request of the incarnation admitted before `set_at` is still queued,
 * running or recovering. `read` is the setting row a caller already read with `syncAdmissionSettingSql`, and its probes
 * when it read them too (`syncAdmissionEffectSql`).
 */
export async function syncAdmissionStatus(engine: Exec, sourceId: string, incarnation: string, read?: SyncAdmissionSettingRow | SyncAdmissionEffectRow): Promise<SyncAdmissionStatus> {
  const { value, raw_set_at } = read ? settingOf(read) : await readSetting(engine);
  const set_at = iso(raw_set_at);
  if (value === 'normal') return { value, set_at, effective: true };
  const probes = effectProbes({ lock: '$1', passOp: '$2', passKey: '$3', setAt: '$4::timestamptz', sourceId: '$5', incarnation: '$6::uuid', kinds: '$7::text[]' });
  const [row] = read && 'pinned' in read && read.pinned !== null && read.destructive !== null ? [read]
    : await engine.executeRaw<{ pinned: boolean; destructive: boolean }>(`SELECT ${probes.pinned} AS pinned, ${probes.destructive} AS destructive`,
      [syncLockId(sourceId), MANAGED_SYNC_PASS_OP, passFingerprint(sourceId, incarnation), raw_set_at, sourceId, incarnation, [...SYNC_ADMISSION_DESTRUCTIVE_KINDS]]);
  return { value, set_at, effective: !row?.pinned && !row?.destructive };
}