Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.3 KB
Raw Blame
/**
 * Purge ledgers and the resurrection guards that read them. One canonical copy
 * used by the schema migration and, through scripts/build-schema.ts FRAGMENTS,
 * by fresh-install DDL.
 *
 * - `fact_purges`: a text-free tombstone per purged claim fingerprint
 *   (gbrain_fact_fingerprint), keyed like `fact_withdrawals`. The facts
 *   guard raises typed `purged_content` for a matching insert or claim
 *   update, whatever its expired_at, so `INSERT ... RETURNING` callers never
 *   see zero rows silently.
 * - `take_purges`: the same tombstone for verbatim take copies; canonical
 *   projections and the takes guard consult it, so a stale takes fence cannot
 *   re-project a purged claim.
 * - `page_purges`: `gbrain delete <slug> --purge` records the purged page's
 *   content hash. A page write whose content hash matches, under any slug,
 *   raises `purged_content`; `gbrain pages unpurge` clears it.
 * - `derivation_inputs`: complete row -> input edges written by every deriver
 *   (`recordDerivationInputs`). Purge walks them transitively to hide derived
 *   rows and mark them `needs_rederive` before cascades delete the evidence.
 * - `needs_rederive`: derived rows a purge hid; a deriver regenerates them from
 *   surviving inputs and deletes the marker.
 *
 * A fingerprint of a short claim is guessable; the ledger proves a claim was
 * purged to someone who already knows it, never what it said.
 */

import { requireLedgerPoliciesSql } from '../derived-state-maintainers.ts';
import { unbackedEntitySql } from './withdrawal-schema.ts';

const RLS = (table: string) => `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 ${table} ENABLE ROW LEVEL SECURITY;
  END IF;
END $rls$;`;

export const MEMORY_PURGE_SCHEMA_SQL = `
CREATE TABLE IF NOT EXISTS fact_purges (
  source_id   TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
  visibility  TEXT NOT NULL CHECK (visibility IN ('private','world')),
  subject     TEXT NOT NULL DEFAULT '*',
  fact_hash   TEXT NOT NULL,
  request_id  UUID,
  actor       TEXT,
  reason      TEXT,
  purged_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (source_id, visibility, subject, fact_hash)
);
${RLS('fact_purges')}
CREATE TABLE IF NOT EXISTS take_purges (
  source_id   TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
  subject     TEXT NOT NULL DEFAULT '*',
  claim_hash  TEXT NOT NULL,
  request_id  UUID,
  purged_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (source_id, subject, claim_hash)
);
${RLS('take_purges')}
CREATE TABLE IF NOT EXISTS page_purges (
  source_id    TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
  content_hash TEXT NOT NULL,
  slug         TEXT NOT NULL,
  request_id   UUID,
  purged_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (source_id, content_hash)
);
${RLS('page_purges')}
CREATE TABLE IF NOT EXISTS derivation_inputs (
  derived_table TEXT NOT NULL,
  derived_id    TEXT NOT NULL,
  input_table   TEXT NOT NULL,
  input_id      TEXT NOT NULL,
  source_id     TEXT REFERENCES sources(id) ON DELETE CASCADE,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (derived_table, derived_id, input_table, input_id)
);
CREATE INDEX IF NOT EXISTS idx_derivation_inputs_input ON derivation_inputs (input_table, input_id);
${RLS('derivation_inputs')}
CREATE TABLE IF NOT EXISTS needs_rederive (
  derived_table TEXT NOT NULL,
  derived_id    TEXT NOT NULL,
  source_id     TEXT REFERENCES sources(id) ON DELETE CASCADE,
  request_id    UUID,
  reason        TEXT NOT NULL,
  marked_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (derived_table, derived_id)
);
${RLS('needs_rederive')}
`;

/**
 * The guards. Installed by the migration only (facts and takes are created by
 * migrations, not schema.sql). Each serializes with a purge through a shared
 * lock on the source row, which the purge holds FOR UPDATE while it writes the
 * ledger and deletes the rows.
 */
/**
 * Page snapshot reads (page-state/snapshot.ts) look up a page's own fact purge
 * tombstones (subject = the slug), the subject-'*' marker (count and latest
 * purged_at) and, lazily, the '*' tombstones naming a fence row's fingerprint.
 * The primary key leads with visibility, so each of those scanned every
 * tombstone of the source (GBRA-69: 4-5 ms per snapshot at 10,000 fact
 * tombstones, about 7 snapshots per import). `fact_purges_subject_idx` serves
 * a page's own tombstones and the lazy '*' lookup by fingerprint;
 * `fact_purges_all_subjects_idx` holds only the '*' rows the marker counts.
 * The import probes that match a fence row against `subject='*' OR
 * subject=slug` (facts/purge-overlay.ts, eligibility/fence-overlay.ts) become
 * a bitmap OR over the pair. Migration v231 builds both (CONCURRENTLY on
 * Postgres).
 */
export const FACT_PURGES_SUBJECT_INDEX = { name: 'fact_purges_subject_idx', table: 'fact_purges',
  sql: 'CREATE INDEX IF NOT EXISTS fact_purges_subject_idx ON fact_purges (source_id, subject, fact_hash) INCLUDE (visibility, purged_at)' } as const;
export const FACT_PURGES_ALL_SUBJECTS_INDEX = { name: 'fact_purges_all_subjects_idx', table: 'fact_purges',
  sql: "CREATE INDEX IF NOT EXISTS fact_purges_all_subjects_idx ON fact_purges (source_id, purged_at) WHERE subject = '*'" } as const;
export const FACT_PURGE_LOOKUP_INDEX_SQL = `
${FACT_PURGES_SUBJECT_INDEX.sql};
${FACT_PURGES_ALL_SUBJECTS_INDEX.sql};
`;

/**
 * The three resurrection guards. Each refuses with writer_coordinator_required (unreadable_state) when row-level
 * security applies to the writing role on a table it reads and no permissive policy of the role covers it, so an empty
 * read under RLS never counts as "not purged" (#7632/#7659, derived-state-maintainers.ts). Migration v318 re-creates
 * the functions alone.
 */
export const REFUSE_PURGED_FACT_FUNCTION_SQL = `CREATE OR REPLACE FUNCTION gbrain_refuse_purged_fact() RETURNS trigger
  LANGUAGE plpgsql SET search_path = pg_catalog, public, pg_temp AS $fn$
  BEGIN
    ${requireLedgerPoliciesSql('fact_purges', ['SELECT'], '    ')}
    PERFORM id FROM sources WHERE id = NEW.source_id FOR SHARE;
    IF EXISTS (SELECT 1 FROM fact_purges
      WHERE source_id = NEW.source_id AND visibility = NEW.visibility
        AND (subject = '*' OR subject = NEW.entity_slug OR ${unbackedEntitySql('NEW')})
        AND fact_hash = gbrain_fact_fingerprint(NEW.fact)) 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(gbrain_fact_fingerprint(NEW.fact), 8))::text;
    END IF;
    RETURN NEW;
  END
  $fn$`;
export const REFUSE_PURGED_TAKE_FUNCTION_SQL = `CREATE OR REPLACE FUNCTION gbrain_refuse_purged_take() RETURNS trigger
  LANGUAGE plpgsql SET search_path = pg_catalog, public, pg_temp AS $fn$
  DECLARE src TEXT; subj TEXT;
  BEGIN
    ${requireLedgerPoliciesSql('pages', ['SELECT'], '    ')}
    ${requireLedgerPoliciesSql('take_purges', ['SELECT'], '    ')}
    SELECT p.source_id, p.slug INTO src, subj FROM pages p WHERE p.id = NEW.page_id;
    IF src IS NOT NULL AND EXISTS (SELECT 1 FROM take_purges
      WHERE source_id = src AND (subject = '*' OR subject = subj)
        AND claim_hash = gbrain_fact_fingerprint(NEW.claim)) THEN
      RAISE EXCEPTION USING ERRCODE = 'P0001',
        MESSAGE = 'purged_content: this take claim was purged from this source and cannot be saved again',
        DETAIL = json_build_object('table', 'takes', 'hash8', left(gbrain_fact_fingerprint(NEW.claim), 8))::text;
    END IF;
    RETURN NEW;
  END
  $fn$`;
export const REFUSE_PURGED_PAGE_FUNCTION_SQL = `CREATE OR REPLACE FUNCTION gbrain_refuse_purged_page() RETURNS trigger
  LANGUAGE plpgsql SET search_path = pg_catalog, public, pg_temp AS $fn$
  BEGIN
    -- No column list on the trigger: a column-scoped trigger would pin pages.source_id and content_hash.
    IF NEW.content_hash IS NOT NULL
      AND (TG_OP = 'INSERT' OR NEW.content_hash IS DISTINCT FROM OLD.content_hash OR NEW.source_id IS DISTINCT FROM OLD.source_id) THEN
      ${requireLedgerPoliciesSql('page_purges', ['SELECT'], '      ')}
      IF EXISTS (SELECT 1 FROM page_purges WHERE source_id = NEW.source_id AND content_hash = NEW.content_hash) THEN
        RAISE EXCEPTION USING ERRCODE = 'P0001',
          MESSAGE = 'purged_content: this page content was purged from this source and cannot be saved again',
          DETAIL = json_build_object('table', 'pages', 'hash8', left(NEW.content_hash, 8))::text;
      END IF;
    END IF;
    RETURN NEW;
  END
  $fn$`;

export const MEMORY_PURGE_GUARD_SQL = `
${REFUSE_PURGED_FACT_FUNCTION_SQL};
DROP TRIGGER IF EXISTS facts_refuse_purged ON facts;
CREATE TRIGGER facts_refuse_purged BEFORE INSERT OR UPDATE OF fact, source_id, visibility, entity_slug ON facts
  FOR EACH ROW EXECUTE FUNCTION gbrain_refuse_purged_fact();
${REFUSE_PURGED_TAKE_FUNCTION_SQL};
DROP TRIGGER IF EXISTS takes_refuse_purged ON takes;
CREATE TRIGGER takes_refuse_purged BEFORE INSERT OR UPDATE OF claim, page_id ON takes
  FOR EACH ROW EXECUTE FUNCTION gbrain_refuse_purged_take();
${REFUSE_PURGED_PAGE_FUNCTION_SQL};
DROP TRIGGER IF EXISTS pages_refuse_purged ON pages;
CREATE TRIGGER pages_refuse_purged BEFORE INSERT OR UPDATE ON pages
  FOR EACH ROW EXECUTE FUNCTION gbrain_refuse_purged_page();
`;