Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.0 KB
Raw Blame
/**
 * The trust policy generation counter in the database (#5575 ENG-11). One
 * canonical copy used by the trust generation schema migration. Like the
 * trust tier DDL (trust/schema.ts) it is not in the schema blob: its triggers
 * read `trust_tier` and `min_trust`, which exist only through migrations, so
 * a fresh install gets it by replaying migrations.
 *
 * `trust_policy_state` holds one row whose `generation` increases whenever a
 * change could make cached proactive content (hot memory, OpenClaw core)
 * wrong: a row's trust tier changes; a page enters or leaves quarantine (or a
 * quarantined page is inserted, deleted, soft-deleted, restored or renamed,
 * which moves the facts its slug hides); a token or client read floor
 * changes; a `trust.%` config key is written; a purge ledger or
 * needs_rederive row is inserted. Ordinary writes never touch it: every
 * trigger is WHEN-guarded.
 *
 * A transactional row on purpose, not a sequence: the bump commits with the
 * content change, so a reader that reads the generation BEFORE the content
 * (eligibility/generation.ts) can only cache content at least as new as the
 * generation it stored, and the next read sees a newer generation and
 * rebuilds. The triggers are deferred constraint triggers, so the counter row
 * is locked once per transaction at commit, after every other row lock the
 * transaction takes: two transactions cannot deadlock on it, and a bulk tier
 * change (backfill) updates it once (`gbrain.trust_generation_bumped`).
 */
import { QUARANTINE_KEY } from '../quarantine.ts';
import { requireMaintainerPoliciesSql } from '../derived-state-maintainers.ts';

export const TRUST_POLICY_STATE_TABLE = 'trust_policy_state';
export const TRUST_GENERATION_FUNCTION = 'gbrain_bump_trust_generation';
/** Trigger names, one per event (a WHEN clause cannot name OLD on INSERT or NEW on DELETE). */
export const TRUST_GENERATION_TRIGGERS = { insert: 'trust_generation_insert', update: 'trust_generation_update', delete: 'trust_generation_delete' } as const;

type GenerationEvent = keyof typeof TRUST_GENERATION_TRIGGERS;

const quarantined = (row: 'NEW' | 'OLD') => `(COALESCE(${row}.frontmatter, '{}'::jsonb) ? '${QUARANTINE_KEY}')`;

/**
 * table -> event -> WHEN predicate. Pinned by test/trust-generation.test.ts,
 * which checks every listed transition bumps and an ordinary write does not.
 */
export const TRUST_GENERATION_WHEN: Readonly<Record<string, Partial<Record<GenerationEvent, string>>>> = {
  facts: { update: 'OLD.trust_tier IS DISTINCT FROM NEW.trust_tier' },
  takes: { update: 'OLD.trust_tier IS DISTINCT FROM NEW.trust_tier' },
  timeline_entries: { update: 'OLD.trust_tier IS DISTINCT FROM NEW.trust_tier' },
  pages: {
    insert: quarantined('NEW'),
    update: `OLD.trust_tier IS DISTINCT FROM NEW.trust_tier OR ${quarantined('OLD')} IS DISTINCT FROM ${quarantined('NEW')}
      OR (${quarantined('NEW')} AND (OLD.deleted_at, OLD.source_id, OLD.slug) IS DISTINCT FROM (NEW.deleted_at, NEW.source_id, NEW.slug))`,
    delete: quarantined('OLD'),
  },
  oauth_clients: { update: 'OLD.min_trust IS DISTINCT FROM NEW.min_trust' },
  access_tokens: { update: 'OLD.min_trust IS DISTINCT FROM NEW.min_trust' },
  config: {
    insert: `NEW.key LIKE 'trust.%'`,
    update: `(OLD.key LIKE 'trust.%' OR NEW.key LIKE 'trust.%') AND (OLD.key, OLD.value) IS DISTINCT FROM (NEW.key, NEW.value)`,
    delete: `OLD.key LIKE 'trust.%'`,
  },
  fact_purges: { insert: 'TRUE' },
  take_purges: { insert: 'TRUE' },
  page_purges: { insert: 'TRUE' },
  // A new or changed flag receipt changes what activation control withholds (CEO-20).
  write_gate_receipts: {
    insert: 'TRUE',
    update: '(OLD.verdict, OLD.reason_families, OLD.content_hash, OLD.target_table, OLD.target_id) IS DISTINCT FROM (NEW.verdict, NEW.reason_families, NEW.content_hash, NEW.target_table, NEW.target_id)',
    delete: 'TRUE',
  },
  needs_rederive: { insert: 'TRUE' },
};

/** Under RLS the writer needs the counter row (#7637, derived-state-maintainers.ts), else a typed refusal at commit. */
export const BUMP_FUNCTION = `CREATE OR REPLACE FUNCTION ${TRUST_GENERATION_FUNCTION}() RETURNS trigger LANGUAGE plpgsql SET search_path = pg_catalog, public, pg_temp AS $fn$
BEGIN
  IF COALESCE(current_setting('gbrain.trust_generation_bumped', true), '') = 'on' THEN RETURN NULL; END IF;
  ${requireMaintainerPoliciesSql(TRUST_POLICY_STATE_TABLE, ['SELECT', 'INSERT', 'UPDATE'])}
  INSERT INTO ${TRUST_POLICY_STATE_TABLE} (id, generation, bumped_at) VALUES (1, 1, now())
    ON CONFLICT (id) DO UPDATE SET generation = ${TRUST_POLICY_STATE_TABLE}.generation + 1, bumped_at = now();
  PERFORM set_config('gbrain.trust_generation_bumped', 'on', true);
  RETURN NULL;
END $fn$`;

/** DROP + CREATE one deferred, WHEN-guarded row trigger (idempotent). */
export function trustGenerationTriggerSql(table: string, event: GenerationEvent, when: string): string[] {
  const name = TRUST_GENERATION_TRIGGERS[event];
  return [
    `DROP TRIGGER IF EXISTS ${name} ON ${table}`,
    `CREATE CONSTRAINT TRIGGER ${name} AFTER ${event.toUpperCase()} ON ${table} DEFERRABLE INITIALLY DEFERRED
      FOR EACH ROW WHEN (${when}) EXECUTE FUNCTION ${TRUST_GENERATION_FUNCTION}()`,
  ];
}

export const TRUST_GENERATION_SCHEMA_STATEMENTS: readonly string[] = [
  `CREATE TABLE IF NOT EXISTS ${TRUST_POLICY_STATE_TABLE} (
  id SMALLINT PRIMARY KEY CHECK (id = 1),
  generation BIGINT NOT NULL DEFAULT 0,
  bumped_at TIMESTAMPTZ NOT NULL DEFAULT now()
)`,
  `DO $rls$ BEGIN
  IF EXISTS (SELECT 1 FROM pg_roles r WHERE pg_has_role(current_user, r.oid, 'USAGE') AND (r.rolbypassrls OR r.rolsuper)) THEN
    ALTER TABLE ${TRUST_POLICY_STATE_TABLE} ENABLE ROW LEVEL SECURITY;
  END IF;
END $rls$`,
  `INSERT INTO ${TRUST_POLICY_STATE_TABLE} (id) VALUES (1) ON CONFLICT (id) DO NOTHING`,
  BUMP_FUNCTION,
  ...Object.entries(TRUST_GENERATION_WHEN).flatMap(([table, events]) =>
    (Object.entries(events) as [GenerationEvent, string][]).flatMap(([event, when]) => trustGenerationTriggerSql(table, event, when))),
];

export const TRUST_GENERATION_SCHEMA_SQL = `${TRUST_GENERATION_SCHEMA_STATEMENTS.join(';\n')};\n`;