Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.9 KB
Raw Blame
/**
 * Set-based insert guards on facts (#7105). One statement-level AFTER INSERT
 * trigger reads the statement's inserted rows from a transition table and
 * applies both insert-time guards once per statement instead of once per row
 * (the withdrawal stamp only for inserts that defer it, see below):
 *
 * - Purge refusal (purge-schema.ts `gbrain_refuse_purged_fact`): an inserted
 *   row whose fingerprint has a fact_purges tombstone for its source,
 *   visibility and subject ('*' or its entity_slug; any subject for a row on an
 *   unbacked name key, GBRA-574 withdrawal-schema.ts unbackedEntitySql) aborts the statement with
 *   the same P0001 `purged_content` message and `{table, hash8}` detail,
 *   whatever its expired_at. When several rows match, the detail names the
 *   first one in insertion order, as the per-row trigger did.
 * - Withdrawal preservation (withdrawal-schema.ts
 *   `gbrain_preserve_fact_withdrawal`): an inserted active row matching a
 *   fact_withdrawals row (v2 or v1 fingerprint) is stamped expired_at =
 *   min(withdrawn_at) and valid_until = LEAST(valid_until, withdrawn_at).
 *   GST-2346: a row on a member page (memory/members/<id>) is stamped only
 *   by that page's own withdrawals, as in gbrain_preserve_fact_withdrawal
 *   (withdrawal-schema.ts); GBRA-574: a row on an unbacked name key by a
 *   withdrawal of its claim under any subject.
 *   By default the per-row BEFORE INSERT trigger facts_preserve_withdrawal_insert
 *   stamps the row before it is written, so `INSERT ... RETURNING` reads the
 *   stamp. An insert made under FACT_WITHDRAWAL_STAMP_DEFERRED_SETTING (the
 *   bulk fence insert in engine-sql/facts.ts, whose RETURNING reads only ids)
 *   skips that trigger through its WHEN clause, which calls no function, and
 *   this guard stamps the rows by an UPDATE of just the matching ones at the
 *   end of the statement. The setting only moves the stamp, never skips it:
 *   the guard stamps every inserted active row still matching, whoever set
 *   it. That UPDATE runs under FACT_WITHDRAWAL_STAMP_SETTING
 *   (attribution-schema.ts), so the row keeps the last_write_* values its
 *   INSERT stamped or supplied, and resets it afterwards. A deferred row's
 *   RETURNING (or a CTE over it) reads it unstamped; the next statement reads
 *   the stamp.
 *
 * Both take the per-row guards' lock: FOR SHARE on each inserted source row
 * before the ledgers are read, so an insert still serializes with a purge or
 * a withdrawal that holds the source FOR UPDATE. A ledger with no row for the
 * inserted sources costs one index probe, not a fingerprint per row.
 *
 * Transition tables cannot be combined with a column list, so updates keep
 * the per-row BEFORE UPDATE OF triggers under their old names and functions;
 * only the insert half moves here. A statement trigger sees only the rows the
 * statement wrote: a row ON CONFLICT DO NOTHING skipped is not checked (it is
 * not saved either). Installed by migration v264.
 *
 * #7632/#7659: a writing role that RLS keeps from reading a ledger, or from updating the rows it inserted when a
 * withdrawal matches, is refused (derived-state-maintainers.ts requireLedgerPoliciesSql) instead of reading the ledger as
 * empty.
 */
import { requireLedgerPoliciesSql } from '../derived-state-maintainers.ts';
import { FACT_WITHDRAWAL_STAMP_SETTING } from '../persistence/attribution-schema.ts';
import { ownedMemorySubjectSql, unbackedEntitySql } from './withdrawal-schema.ts';

export const FACT_INSERT_GUARD_TRIGGER = 'facts_guard_inserted';
/** Transaction-local; 'on' defers the withdrawal stamp of the following inserts to facts_guard_inserted. */
export const FACT_WITHDRAWAL_STAMP_DEFERRED_SETTING = 'gbrain.fact_withdrawal_stamp_deferred';
export const FACT_INSERT_GUARD_FUNCTION = 'gbrain_guard_inserted_facts';

/**
 * #7778: `outcomeMarkerSql('i')` from facts/audit-sources.ts, spelled out so this schema fragment imports no module
 * outside the PGLite snapshot inputs; test/conversation-facts-outcome-marker-purge-7778.test.ts pins the two equal.
 */
export const GUARD_OUTCOME_MARKER_SQL = "(i.source IN ('cli:extract-conversation-facts:terminal:v2','cli:extract-conversation-facts:non-extractable:v2','cli:extract-conversation-facts:terminal') AND i.fact IN ('EXTRACTION_COMPLETE','EXTRACTION_NOT_APPLICABLE'))";

/** The WITH clause naming, as m, the active inserted facts a withdrawal matches and its earliest withdrawn_at. */
const WITHDRAWN_INSERTS_SQL = `WITH n AS MATERIALIZED (
        SELECT i.id, i.source_id, i.visibility, i.entity_slug, i.source_markdown_slug, ${unbackedEntitySql('i')} AS unbacked,
          gbrain_fact_fingerprint(i.fact) AS fact_hash, gbrain_fact_fingerprint_v1(i.fact) AS fact_hash_v1
        FROM inserted_facts i WHERE i.expired_at IS NULL),
      m AS (
        SELECT n.id, min(w.withdrawn_at) AS withdrawn_at FROM n JOIN fact_withdrawals w
          ON w.source_id = n.source_id AND w.visibility = n.visibility
          AND (CASE WHEN starts_with(COALESCE(n.source_markdown_slug, ''), 'memory/members/') THEN w.subject = n.source_markdown_slug
            ELSE (n.unbacked AND NOT ${ownedMemorySubjectSql('w.subject')}) OR w.subject IN ('*', n.entity_slug) END) AND w.fact_hash IN (n.fact_hash, n.fact_hash_v1)
        GROUP BY n.id)`;

/**
 * The guard function alone (#7778 re-creates it without touching the triggers). The purge refusal skips an extraction
 * outcome row (facts/audit-sources.ts `isOutcomeMarker`): that bookkeeping marker is not a claim, and a subject-'*'
 * tombstone on its fingerprint, which a page purge wrote before #7778, kept every page of the source from completing.
 */
export const FACT_INSERT_GUARD_FUNCTION_SQL = `
CREATE OR REPLACE FUNCTION gbrain_guard_inserted_facts() RETURNS trigger
  LANGUAGE plpgsql SET search_path = pg_catalog, public, pg_temp AS $fn$
  DECLARE purged TEXT; stamp_setting TEXT;
  BEGIN
    ${requireLedgerPoliciesSql('fact_purges', ['SELECT'], '    ')}
    PERFORM s.id FROM sources s WHERE s.id IN (SELECT i.source_id FROM inserted_facts i) ORDER BY s.id FOR SHARE OF s;
    IF EXISTS (SELECT 1 FROM fact_purges p WHERE p.source_id IN (SELECT i.source_id FROM inserted_facts i)) THEN
      WITH n AS MATERIALIZED (
        SELECT row_number() OVER () AS ord, i.source_id, i.visibility, i.entity_slug, gbrain_fact_fingerprint(i.fact) AS fact_hash
        FROM inserted_facts i WHERE NOT ${GUARD_OUTCOME_MARKER_SQL})
      SELECT n.fact_hash INTO purged FROM n
        WHERE EXISTS (SELECT 1 FROM fact_purges p WHERE p.source_id = n.source_id AND p.visibility = n.visibility
          AND (p.subject IN ('*', n.entity_slug) OR ${unbackedEntitySql('n')}) AND p.fact_hash = n.fact_hash)
        ORDER BY n.ord LIMIT 1;
      IF purged IS NOT NULL THEN
        RAISE EXCEPTION USING ERRCODE = 'P0001',
          MESSAGE = 'purged_content: this claim was purged from this source and cannot be saved again',
          DETAIL = json_build_object('table', 'facts', 'hash8', left(purged, 8))::text;
      END IF;
    END IF;
    IF EXISTS (SELECT 1 FROM inserted_facts i WHERE i.expired_at IS NULL) THEN
      ${requireLedgerPoliciesSql('fact_withdrawals', ['SELECT'], '      ')}
    END IF;
    IF EXISTS (SELECT 1 FROM fact_withdrawals w WHERE w.source_id IN (SELECT i.source_id FROM inserted_facts i WHERE i.expired_at IS NULL)) THEN
      IF EXISTS (${WITHDRAWN_INSERTS_SQL} SELECT 1 FROM m) THEN
        ${requireLedgerPoliciesSql('facts', ['SELECT', 'UPDATE'], '        ')}
      END IF;
      stamp_setting := current_setting('${FACT_WITHDRAWAL_STAMP_SETTING}', true);
      PERFORM set_config('${FACT_WITHDRAWAL_STAMP_SETTING}', 'on', true);
      ${WITHDRAWN_INSERTS_SQL}
      UPDATE facts f SET expired_at = m.withdrawn_at, valid_until = LEAST(COALESCE(f.valid_until, m.withdrawn_at), m.withdrawn_at)
        FROM m WHERE f.id = m.id;
      PERFORM set_config('${FACT_WITHDRAWAL_STAMP_SETTING}', COALESCE(stamp_setting, ''), true);
    END IF;
    RETURN NULL;
  END
  $fn$;
`;

export const FACT_INSERT_GUARD_SQL = `${FACT_INSERT_GUARD_FUNCTION_SQL}
DROP TRIGGER IF EXISTS facts_guard_inserted ON facts;
CREATE TRIGGER facts_guard_inserted AFTER INSERT ON facts REFERENCING NEW TABLE AS inserted_facts
  FOR EACH STATEMENT EXECUTE FUNCTION gbrain_guard_inserted_facts();
DROP TRIGGER IF EXISTS facts_refuse_purged ON facts;
CREATE TRIGGER facts_refuse_purged BEFORE UPDATE OF fact, source_id, visibility, entity_slug ON facts
  FOR EACH ROW EXECUTE FUNCTION gbrain_refuse_purged_fact();
DROP TRIGGER IF EXISTS facts_preserve_withdrawal ON facts;
CREATE TRIGGER facts_preserve_withdrawal BEFORE UPDATE OF fact, source_id, visibility, entity_slug, expired_at ON facts
  FOR EACH ROW EXECUTE FUNCTION gbrain_preserve_fact_withdrawal();
DROP TRIGGER IF EXISTS facts_preserve_withdrawal_insert ON facts;
CREATE TRIGGER facts_preserve_withdrawal_insert BEFORE INSERT ON facts FOR EACH ROW
  WHEN (NEW.expired_at IS NULL AND COALESCE(current_setting('${FACT_WITHDRAWAL_STAMP_DEFERRED_SETTING}', true), '') <> 'on')
  EXECUTE FUNCTION gbrain_preserve_fact_withdrawal();
`;