Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
19.9 KB
Raw Blame
/**
 * Memory trust tiers (#5575) in the database: the `trust_tier` and
 * `write_origin` columns, the BEFORE ROW trigger that stamps and guards them,
 * the page_versions snapshot, the per-token `min_trust` read floor and the
 * `trust_proposals` decision record. One canonical copy used by the trust
 * tiers schema migration. Like the attribution DDL it is not in the schema
 * blob: a fresh install replays every migration.
 *
 * The writer's tier reaches the trigger through transaction-local settings
 * that the attribution seam sets (persistence/context.ts):
 *   gbrain.write_trust_tier       the effective tier (trust/tier.ts computes it once)
 *   gbrain.write_origin           its origin record, JSON text
 *   gbrain.write_trust_promotion  a tier ceiling for an explicit raise (owner confirmation, CEO-9)
 *   gbrain.write_trust_backfill   'on' for the deterministic backfill (CEO-10)
 *   gbrain.write_trust_keep       comma list of tables whose content rewrites in this scope keep the
 *                                 stored tier: a gbrain-managed fence edit (remember/takes fence append,
 *                                 forget or accept strike) rewrites the page body without authoring it,
 *                                 and the fence row carries its own tier (ENG-1)
 *
 * Trigger semantics (CEO-12, CEO-16, CEO-10, ENG-13):
 * - INSERT: the row gets the writer's tier, or `unknown` without one; a
 *   supplied value is honored only under the backfill setting (never above
 *   operator_curated without promotion).
 * - UPDATE that changes a TRUST_CONTENT_COLUMNS column: an owner-tier writer
 *   (operator_curated or higher) restamps the row to its tier; any lower
 *   writer (or none, read as `unknown`) sets min(prior tier, writer tier).
 * - UPDATE that changes no content column keeps the stored tier, and so does
 *   a content change on a table named by gbrain.write_trust_keep (a fence
 *   edit; it can still lower, never raise).
 * - An UPDATE that sets a higher tier is honored under a covering promotion
 *   ceiling, or under the backfill setting from `unknown` to anything below
 *   user_confirmed. Inside a writer scope it is otherwise clamped back; with
 *   no writer scope it raises `trust_raise_refused`. Lowering is always allowed.
 * - A writer tier above operator_curated needs a covering promotion ceiling.
 * - Guest sources (GBRA-504, guest-notes migration): a pages row in a source listed in
 *   guest_sources never ends above that source's trust_ceiling, on every exit;
 *   creating it or changing its content needs the principal of
 *   gbrain.write_principal_kind/_id on the source's writer list; facts, takes
 *   and timeline rows there are refused. GUEST_AWARE_STAMP_TIER_FUNCTION.
 *
 * `gbrain.write_trust_promotion` protects against bugs, not against a process
 * holding a raw database connection, which can set any setting.
 */
import { HASH_EPHEMERAL_FRONTMATTER_KEYS } from '../utils.ts';
import { OWNER_TIER_FLOOR, TRUST_TIERS, trustRankSql } from './tier.ts';
import { requireMaintainerPoliciesSql } from '../derived-state-maintainers.ts';

export type TrustTable = 'facts' | 'takes' | 'timeline_entries' | 'pages';
export const TRUST_TABLES: readonly TrustTable[] = ['facts', 'takes', 'timeline_entries', 'pages'];
/** Config key: when the last complete backfill apply finished (doctor `trust_tiers` stops recommending the backfill). */
export const TRUST_BACKFILL_COMPLETED_KEY = 'trust.backfill_completed_at';

/**
 * Frontmatter keys whose change is not a content change for the tier rule:
 * the hash-ephemeral keys (timestamps and gate-owned markers re-derived on
 * every import) and the stored quarantine override. The lower-only
 * `trust_tier` marker is content on purpose: deleting it by hand is the
 * owner act that lets the next owner sync restamp the page (CEO-21).
 */
export const TRUST_EPHEMERAL_FRONTMATTER_KEYS: readonly string[] = [...HASH_EPHEMERAL_FRONTMATTER_KEYS.filter(key => key !== 'trust_tier'), 'quarantine_override'];

/**
 * ENG-2: the columns whose change is a content rewrite. Lifecycle and
 * placement columns (expiry, supersession, consolidation, row numbers,
 * visibility, notability, confidence, active, resolution, weight, source)
 * keep the stored tier. Pages use the pages_knowledge_revision tuple
 * (page-state/schema.ts) with the ephemeral frontmatter keys removed.
 * Pinned by test/trust-tier-schema.test.ts.
 */
export const TRUST_CONTENT_COLUMNS: Readonly<Record<TrustTable, readonly string[]>> = {
  facts: ['fact', 'entity_slug', 'kind', 'claim_metric', 'claim_value', 'claim_unit', 'claim_period', 'value', 'event_type', 'dimension', 'context'],
  takes: ['claim', 'kind', 'holder'],
  timeline_entries: ['summary', 'detail', 'date'],
  pages: ['source_id', 'slug', 'type', 'page_kind', 'title', 'compiled_truth', 'timeline', 'frontmatter', 'deleted_at'],
};

/** Columns the migration adds to every trust table (and to page_versions, nullable there). */
export const TRUST_ROW_COLUMNS = ['trust_tier', 'write_origin'] as const;

export const TRUST_TIER_TRIGGER = 'trust_tier_stamp';
export const TRUST_VERSION_TRIGGER = 'page_versions_trust_snapshot';
/** Triggers that must fire before the tier trigger on the same row (PostgreSQL fires same-timing triggers by name). */
export const TRUST_TIER_TRIGGER_PREDECESSORS: Readonly<Record<TrustTable, readonly string[]>> = {
  facts: ['facts_preserve_withdrawal', 'gbrain_write_attribution', 'managed_writer_guard'],
  takes: ['gbrain_write_attribution', 'managed_writer_guard'],
  timeline_entries: ['gbrain_write_attribution', 'managed_writer_guard'],
  pages: ['managed_writer_guard', 'pages_knowledge_revision', 'pages_revision_attribution', 'trg_pages_search_vector'],
};

const tierList = TRUST_TIERS.map(tier => `'${tier}'`).join(',');
const rank = trustRankSql;
const lowerOf = (a: string, b: string) => `(CASE WHEN ${rank(a)} <= ${rank(b)} THEN ${a} ELSE ${b} END)`;
const contentExpr = (row: 'NEW' | 'OLD', table: TrustTable, columns: readonly string[]) => columns
  .map(column => table === 'pages' && column === 'frontmatter'
    // A non-object frontmatter (legacy or raw-SQL rows) has no keys to drop; jsonb `-` would raise on it.
    ? `(CASE WHEN jsonb_typeof(${row}.frontmatter) = 'object' THEN ${row}.frontmatter - ARRAY[${TRUST_EPHEMERAL_FRONTMATTER_KEYS.map(key => `'${key}'`).join(',')}]::text[] ELSE ${row}.frontmatter END)`
    : `${row}.${column}`)
  .join(', ');
const contentChanged = (table: TrustTable, columns: readonly string[] = TRUST_CONTENT_COLUMNS[table]) =>
  `(${contentExpr('NEW', table, columns)}) IS DISTINCT FROM (${contentExpr('OLD', table, columns)})`;
const refuse = (message: string, detail: string) => `RAISE EXCEPTION USING ERRCODE='P0001', MESSAGE='trust_raise_refused: ${message}',
      TABLE=TG_TABLE_NAME, SCHEMA=TG_TABLE_SCHEMA, CONSTRAINT='trust_tier_guard', DETAIL=${detail}`;
const SETTINGS = `
  writer := NULLIF(current_setting('gbrain.write_trust_tier', true), '');
  origin_text := NULLIF(current_setting('gbrain.write_origin', true), '');
  promo := NULLIF(current_setting('gbrain.write_trust_promotion', true), '');
  backfill := COALESCE(current_setting('gbrain.write_trust_backfill', true), '') = 'on';
  keep := TG_TABLE_NAME = ANY(string_to_array(COALESCE(current_setting('gbrain.write_trust_keep', true), ''), ','));
  IF ${rank('writer')} = 0 AND writer IS NOT NULL OR ${rank('promo')} = 0 AND promo IS NOT NULL THEN
    RAISE EXCEPTION USING ERRCODE='22023', MESSAGE='gbrain trust setting names no tier', CONSTRAINT='trust_tier_guard';
  END IF;`;

/** A guest page's content for the writer backstop: every content column but deleted_at, so soft delete and restore pass. */
const GUEST_PAGE_CONTENT_COLUMNS = TRUST_CONTENT_COLUMNS.pages.filter(column => column !== 'deleted_at');
const guestRefuse = (code: string, message: string) => `RAISE EXCEPTION USING ERRCODE='P0001', MESSAGE='${code}: ${message}',
      TABLE=TG_TABLE_NAME, SCHEMA=TG_TABLE_SCHEMA, CONSTRAINT='guest_source_guard', DETAIL=jsonb_build_object('op',TG_OP)::text`;
const CHANGED_CHAIN = `${TRUST_TABLES.map((table, index) => `${index === 0 ? 'IF' : 'ELSIF'} TG_TABLE_NAME = '${table}' THEN
    changed := ${contentChanged(table)};`).join('\n  ')}
  ELSE
    RAISE EXCEPTION 'gbrain_stamp_trust_tier is not classified for table %', TG_TABLE_NAME;
  END IF;`;
/**
 * GBRA-504: the guest-source rules, run before anything else. A page in a guest
 * source (guest_sources, one primary-key probe) may be inserted, or have a
 * content column other than deleted_at changed (moves in or out included), only
 * by a principal on the source's writer list, read from the attribution
 * settings, and only by a guest note: its publication sets gbrain.guest_note to
 * its gbrain.write_request (guests/admission.ts assertGuestWriterAtPublication), so a
 * listed writer's plain write admitted before the source became a guest source
 * is refused here (guest_attribution_missing) without a read of its own. A
 * fact, take or timeline row in a guest source is refused on INSERT and on a
 * content change; lifecycle updates and deletes pass. Other tables skip the
 * probe while guest_sources is empty. `failClosed` (follow-up 3 of #9354) first refuses, with
 * writer_coordinator_required (unreadable_state, state guest_sources), a role that row-level security keeps from
 * reading guest_sources, which would otherwise read it empty and pass every write as if no source were a guest source.
 */
const guestGuard = (failClosed: boolean) => `
  IF TG_OP = 'UPDATE' THEN
    ${CHANGED_CHAIN.replace(/\n/g, '\n  ')}
  END IF;
  IF TG_TABLE_NAME = 'pages' THEN${failClosed ? `
    ${requireMaintainerPoliciesSql('guest_sources', ['SELECT'], '    ')}` : ''}
    SELECT g.trust_ceiling, g.writers INTO guest_ceiling, guest_writers FROM guest_sources g WHERE g.source_id = NEW.source_id;
    guest := FOUND;
    IF NOT guest AND TG_OP = 'UPDATE' AND OLD.source_id IS DISTINCT FROM NEW.source_id THEN
      SELECT g.writers INTO guest_writers FROM guest_sources g WHERE g.source_id = OLD.source_id;
      guest := FOUND;
    END IF;
    IF guest AND NOT COALESCE(NULLIF(current_setting('gbrain.write_principal_kind', true), '') || ':'
        || NULLIF(current_setting('gbrain.write_principal_id', true), '') = ANY(guest_writers), false) THEN
      IF TG_OP = 'INSERT' THEN
        ${guestRefuse('source_writer_restricted', 'only the listed writers of a guest source may create its pages')};
      ELSIF ${contentChanged('pages', GUEST_PAGE_CONTENT_COLUMNS)} THEN
        ${guestRefuse('source_writer_restricted', 'only the listed writers of a guest source may change its pages')};
      END IF;
    ELSIF guest AND (TG_OP = 'INSERT' OR ${contentChanged('pages', GUEST_PAGE_CONTENT_COLUMNS)}) AND NOT COALESCE(
        NULLIF(current_setting('gbrain.guest_note', true), '') = current_setting('gbrain.write_request', true), false) THEN
      ${guestRefuse('guest_attribution_missing', 'a listed writer creates or changes a guest page only as a guest note')};
    END IF;
  ELSIF (TG_OP = 'INSERT' OR changed)${failClosed ? ` THEN
    ${requireMaintainerPoliciesSql('guest_sources', ['SELECT'], '    ')}
  END IF;
  IF TG_TABLE_NAME <> 'pages' AND (TG_OP = 'INSERT' OR changed)` : ''} AND EXISTS (SELECT 1 FROM guest_sources) THEN
    IF TG_TABLE_NAME = 'facts' THEN
      guest := EXISTS (SELECT 1 FROM guest_sources g WHERE g.source_id = NEW.source_id);
    ELSE
      guest := EXISTS (SELECT 1 FROM pages p JOIN guest_sources g ON g.source_id = p.source_id WHERE p.id = NEW.page_id);
    END IF;
    IF guest THEN
      ${guestRefuse('guest_page_immutable', 'a guest source holds no facts, takes or timeline entries')};
    END IF;
  END IF;`;
/** Every exit of the guest-aware function caps a guest page at its source ceiling. */
const GUEST_CEILING_RETURN = `IF guest_ceiling IS NOT NULL AND ${rank('NEW.trust_tier')} > ${rank('guest_ceiling')} THEN NEW.trust_tier := guest_ceiling; END IF; RETURN NEW;`;

/**
 * The tier trigger function. `'none'` is the v226 body, kept
 * byte-identical (the migration golden pins it, and migrations between v226 and
 * the guest-notes migration run before guest_sources exists). `'guest'` adds the guest-source rules
 * (guestGuard) and the per-source ceiling on every RETURN NEW, as the guest-notes migration installed it (byte-identical
 * too); `'guest_fail_closed'` adds the unreadable guest_sources refusal, and any later migration that re-creates this
 * function uses it.
 */
const stampTierFunction = (mode: 'none' | 'guest' | 'guest_fail_closed') => {
  const guestSources = mode !== 'none';
  const ret = guestSources ? GUEST_CEILING_RETURN : 'RETURN NEW;';
  return `CREATE OR REPLACE FUNCTION gbrain_stamp_trust_tier() RETURNS trigger LANGUAGE plpgsql SET search_path = pg_catalog, public, pg_temp AS $fn$
DECLARE writer text; origin_text text; promo text; backfill boolean; keep boolean; changed boolean; effective text;${guestSources ? ' guest boolean := false; guest_ceiling text; guest_writers text[];' : ''}
BEGIN${SETTINGS}${guestSources ? guestGuard(mode === 'guest_fail_closed') : ''}
  IF ${rank('writer')} > ${rank(`'${OWNER_TIER_FLOOR}'`)} AND (promo IS NULL OR ${rank('writer')} > ${rank('promo')}) THEN
    ${refuse('a write declared a tier above operator_curated without owner confirmation', `jsonb_build_object('op',TG_OP,'writer',writer)::text`)};
  END IF;
  IF TG_OP = 'INSERT' THEN
    IF backfill THEN
      IF ${rank('NEW.trust_tier')} > ${rank(`'${OWNER_TIER_FLOOR}'`)} AND (promo IS NULL OR ${rank('NEW.trust_tier')} > ${rank('promo')}) THEN
        ${refuse('a copied row named a tier above operator_curated without owner confirmation', `jsonb_build_object('op',TG_OP,'to',NEW.trust_tier)::text`)};
      END IF;
      ${ret}
    END IF;
    NEW.trust_tier := COALESCE(writer, 'unknown');
    NEW.write_origin := origin_text::jsonb;
    ${ret}
  END IF;
  IF ${rank('NEW.trust_tier')} > ${rank('OLD.trust_tier')} THEN
    IF promo IS NOT NULL AND ${rank('NEW.trust_tier')} <= ${rank('promo')} THEN
      ${ret}
    ELSIF backfill AND OLD.trust_tier = 'unknown' AND NEW.trust_tier <> 'user_confirmed' THEN
      ${ret}
    ELSIF writer IS NULL THEN
      ${refuse('raising a tier needs owner confirmation', `jsonb_build_object('op',TG_OP,'from',OLD.trust_tier,'to',NEW.trust_tier,'backfill',backfill)::text`)};
    END IF;
    NEW.trust_tier := OLD.trust_tier;
  END IF;${guestSources ? '' : `
  ${CHANGED_CHAIN}`}
  IF changed AND NOT keep THEN
    effective := COALESCE(writer, 'unknown');
    IF ${rank('effective')} < ${rank(`'${OWNER_TIER_FLOOR}'`)} THEN effective := ${lowerOf('OLD.trust_tier', 'effective')}; END IF;
    IF ${rank('NEW.trust_tier')} < ${rank('OLD.trust_tier')} THEN effective := ${lowerOf('NEW.trust_tier', 'effective')}; END IF;
    NEW.trust_tier := effective;
    IF NEW.write_origin IS NOT DISTINCT FROM OLD.write_origin THEN NEW.write_origin := origin_text::jsonb; END IF;
  END IF;
  ${ret}
END $fn$`;
};
const STAMP_TIER_FUNCTION = stampTierFunction('none');
/** The tier trigger function as the guest-notes migration installed it (its body is pinned there). */
export const GUEST_AWARE_STAMP_TIER_FUNCTION = stampTierFunction('guest');
/** The current tier trigger function: guest-source rules that refuse a role unable to read guest_sources. */
export const GUEST_FAIL_CLOSED_STAMP_TIER_FUNCTION = stampTierFunction('guest_fail_closed');

/**
 * A version row snapshots the page before the archiving write changes it, in
 * the same transaction, so the page row still carries the snapshotted tier
 * (ENG-10). A supplied value is honored only under the backfill setting.
 * Under RLS the archiving writer needs the page (#7637, derived-state-maintainers.ts).
 */
export const SNAPSHOT_VERSION_FUNCTION = `CREATE OR REPLACE FUNCTION gbrain_snapshot_version_trust() RETURNS trigger LANGUAGE plpgsql SET search_path = pg_catalog, public, pg_temp AS $fn$
BEGIN
  IF COALESCE(current_setting('gbrain.write_trust_backfill', true), '') = 'on' AND NEW.trust_tier IS NOT NULL THEN RETURN NEW; END IF;
  ${requireMaintainerPoliciesSql('pages', ['SELECT'])}
  SELECT p.trust_tier, p.write_origin INTO NEW.trust_tier, NEW.write_origin FROM pages p WHERE p.id = NEW.page_id;
  RETURN NEW;
END $fn$`;

/** NOT VALID first (no scan under the ADD), then a separate validation pass. */
const checkConstraint = (table: string, name: string, predicate: string) => [
  `DO $do$ BEGIN
    IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = '${name}' AND conrelid = '${table}'::regclass) THEN
      ALTER TABLE ${table} ADD CONSTRAINT ${name} CHECK (${predicate}) NOT VALID;
    END IF;
  END $do$`,
  `ALTER TABLE ${table} VALIDATE CONSTRAINT ${name}`,
];

export const TRUST_PROPOSAL_ACTIONS = ['supersede_fact', 'supersede_take', 'forget', 'lower_page', 'confirm'] as const;
export const TRUST_PROPOSAL_STATUSES = ['pending', 'accepted', 'rejected', 'undone', 'superseded'] as const;
const list = (values: readonly string[]) => values.map(value => `'${value}'`).join(',');
const TRUST_TABLE_LIST = list(TRUST_TABLES);

/**
 * ENG-4: one typed trust-decision record. Handlers (lane L1) reuse the
 * decide_proposals coordinator primitives; CLI refs are `tp<id>`. `target`
 * is the row the decision changes; `related` is the row that caused it (the
 * contested lower-tier fact of a guarded supersession, the agent version of a
 * lowered page). before_state/after_state hold tiers, ids and revisions, the
 * exact state the accept path re-checks under lock.
 */
const TRUST_PROPOSALS_DDL = `CREATE TABLE IF NOT EXISTS trust_proposals (
  id BIGSERIAL PRIMARY KEY,
  action TEXT NOT NULL CHECK (action IN (${list(TRUST_PROPOSAL_ACTIONS)})),
  source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
  target_table TEXT NOT NULL CHECK (target_table IN (${TRUST_TABLE_LIST})),
  target_id BIGINT NOT NULL,
  related_table TEXT CHECK (related_table IN (${TRUST_TABLE_LIST})),
  related_id BIGINT,
  before_state JSONB NOT NULL DEFAULT '{}'::jsonb,
  after_state JSONB NOT NULL DEFAULT '{}'::jsonb,
  proposer TEXT NOT NULL,
  proposer_principal_kind TEXT,
  proposer_principal_id TEXT,
  write_request_id UUID,
  status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN (${list(TRUST_PROPOSAL_STATUSES)})),
  decided_at TIMESTAMPTZ,
  decided_principal_kind TEXT,
  decided_principal_id TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  CHECK ((related_table IS NULL) = (related_id IS NULL))
)`;

export const TRUST_SCHEMA_STATEMENTS = [
  ...TRUST_TABLES.map(table => `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS trust_tier TEXT NOT NULL DEFAULT 'unknown', ADD COLUMN IF NOT EXISTS write_origin JSONB`),
  ...TRUST_TABLES.flatMap(table => checkConstraint(table, `${table}_trust_tier_check`, `trust_tier IN (${tierList})`)),
  `ALTER TABLE page_versions ADD COLUMN IF NOT EXISTS trust_tier TEXT, ADD COLUMN IF NOT EXISTS write_origin JSONB`,
  ...checkConstraint('page_versions', 'page_versions_trust_tier_check', `trust_tier IS NULL OR trust_tier IN (${tierList})`),
  ...['oauth_clients', 'access_tokens'].flatMap(table => [
    `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS min_trust TEXT`,
    ...checkConstraint(table, `${table}_min_trust_check`, `min_trust IS NULL OR min_trust IN (${tierList})`),
  ]),
  TRUST_PROPOSALS_DDL,
  `CREATE INDEX IF NOT EXISTS trust_proposals_pending_idx ON trust_proposals (source_id, created_at) WHERE status = 'pending'`,
  `CREATE INDEX IF NOT EXISTS trust_proposals_target_idx ON trust_proposals (target_table, target_id)`,
  `CREATE UNIQUE INDEX IF NOT EXISTS trust_proposals_pending_unique ON trust_proposals
    (action, target_table, target_id, COALESCE(related_table, ''), COALESCE(related_id, 0)) WHERE status = 'pending'`,
  STAMP_TIER_FUNCTION,
  SNAPSHOT_VERSION_FUNCTION,
  ...TRUST_TABLES.flatMap(table => [
    `DROP TRIGGER IF EXISTS ${TRUST_TIER_TRIGGER} ON ${table}`,
    `CREATE TRIGGER ${TRUST_TIER_TRIGGER} BEFORE INSERT OR UPDATE ON ${table} FOR EACH ROW EXECUTE FUNCTION gbrain_stamp_trust_tier()`,
  ]),
  `DROP TRIGGER IF EXISTS ${TRUST_VERSION_TRIGGER} ON page_versions`,
  `CREATE TRIGGER ${TRUST_VERSION_TRIGGER} BEFORE INSERT ON page_versions FOR EACH ROW EXECUTE FUNCTION gbrain_snapshot_version_trust()`,
] as const;

export const TRUST_SCHEMA_SQL = `${TRUST_SCHEMA_STATEMENTS.join(';\n')};\n`;