Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.8 KB
Raw Blame
/**
 * The one history reader of the belief ledger (docs/designs/BELIEF_LEDGER.md
 * section 8, privacy). Every read of events goes through `readBeliefHistory`;
 * remote callers never touch the table. A remote caller sees an event only when
 * all hold, and the read fails closed when an owner cannot be resolved:
 *   - the event's own visibility was `world` when recorded, and no later
 *     event of the same claim (any key, so a fact moved to `private`) is
 *     private: making a claim private hides its earlier world history;
 *   - the stream page's current lifetime is visible now (a page made private
 *     later hides its earlier events; an ended lifetime hides them too), and
 *     for facts and takes it is not quarantined (#6259: a quarantined page's
 *     claims are scraped text, kept from remote readers as its body is);
 *   - for links, every page-backed endpoint and the origin are visible now;
 *   - for takes, the take's holder is one the caller may read (`takesHolders`, default `['world']`, the takes
 *     surfaces' rule). A removal carries no value, so its holder is the key's newest earlier value's (one key is one
 *     holder); a take whose values were all purged has no holder and is hidden.
 * For every caller, a key with a `derived.hidden` (a purge hid the row it
 * describes, section 6.5) hides its events below that marker and its backfill
 * events at any id; the marker itself stays visible as the disclosure. Only
 * the source's current incarnation is read: a removed and re-added source
 * inherits no history.
 */
import type { BrainEngine } from '../engine.ts';
import { remoteReadFloorSql } from '../search/private-visibility.ts';
import { quarantineFilterFragment } from '../quarantine.ts';

export interface BeliefHistoryRow {
  id: number; slug: string; page_lifetime: string | null; subject_kind: string; subject_key: string; event_type: string; origin: string;
  trust_tier: string; writer_tier: string | null; tier_basis: string; visibility: string; recorded_at: string; source_time: string | null;
  value: Record<string, unknown> | null; value_hash: string | null; prior_hash: string | null; state_hash: string; cause: Record<string, unknown>;
  purged: boolean; redacted_fields: string[] | null;
}

export interface BeliefHistoryQuery {
  sourceId: string; slug?: string; subjectKey?: string; remote: boolean; afterId?: number; limit?: number;
  /** Recorded-time window (after, until]. */
  recordedAfter?: string; recordedUntil?: string;
  /** Only these subject keys, below this event id (the history of keys before a window, read newest first with `descending`). */
  subjectKeys?: readonly string[]; beforeId?: number; descending?: boolean;
  /** Remote callers: the take holders they may read (the takes surfaces' allow-list); `['world']` when absent. */
  takesHolders?: readonly string[];
}

/** Lifetimes a link key names (`L:<uuid>` components), for the endpoint visibility rule. */
function linkLifetimes(subjectKey: string): string[] {
  const parts = JSON.parse(subjectKey) as unknown[];
  const flat = parts[0] === 'lt' ? (parts[1] as unknown[]) : parts;
  return flat.filter((p): p is string => typeof p === 'string' && p.startsWith('L:')).map(p => p.slice(2));
}

export async function readBeliefHistory(engine: BrainEngine, q: BeliefHistoryQuery): Promise<BeliefHistoryRow[]> {
  return (await readBeliefHistoryPage(engine, q)).rows;
}

/**
 * One page of history and how far it read: `scanned` rows matched the query before the remote filter, the last of them
 * `lastScannedId`. A remote page can hold fewer rows than `limit` and still not be the last; page on these, never on
 * `rows.length`.
 */
export async function readBeliefHistoryPage(engine: BrainEngine, q: BeliefHistoryQuery): Promise<{ rows: BeliefHistoryRow[]; scanned: number; lastScannedId: number | null }> {
  const rows = await engine.executeRaw<BeliefHistoryRow & { stream_visible: boolean | null; later_private: boolean; take_holder: string | null }>(`SELECT e.id, e.slug, e.page_lifetime::text AS page_lifetime,
      e.subject_kind, e.subject_key, e.event_type, e.origin, e.trust_tier, e.writer_tier, e.tier_basis, e.visibility, e.recorded_at, e.source_time,
      e.value, e.value_hash, e.prior_hash, e.state_hash, e.cause, e.purged, e.redacted_fields,
      (SELECT ${remoteReadFloorSql('p')} AND (e.subject_kind NOT IN ('fact', 'take') OR ${quarantineFilterFragment('p')}) FROM belief_page_lifetimes l JOIN pages p ON p.source_id = l.source_id AND p.slug = l.slug
        AND p.deleted_at IS NULL AND (l.page_id IS NULL OR p.id = l.page_id)
        WHERE l.page_lifetime = e.page_lifetime AND l.ended_at IS NULL) AS stream_visible,
      (e.claim_fp IS NOT NULL AND EXISTS (SELECT 1 FROM belief_events v WHERE v.source_id = e.source_id AND v.source_incarnation = e.source_incarnation
        AND v.claim_fp = e.claim_fp AND v.subject_kind = e.subject_kind AND v.visibility = 'private' AND v.id > e.id)) AS later_private,
      CASE WHEN e.subject_kind = 'take' THEN COALESCE(e.value->>'holder', (SELECT t.value->>'holder' FROM belief_events t WHERE t.source_id = e.source_id
        AND t.source_incarnation = e.source_incarnation AND t.subject_kind = 'take' AND t.subject_key = e.subject_key AND t.id < e.id AND t.value->>'holder' IS NOT NULL
        ORDER BY t.id DESC LIMIT 1)) END AS take_holder
    FROM belief_events e
    WHERE e.source_id = $1 AND e.source_incarnation = (SELECT s.incarnation FROM sources s WHERE s.id = $1) AND ($2::text IS NULL OR e.slug = $2) AND ($3::text IS NULL OR e.subject_key = $3) AND e.id > $4
      AND ($6::timestamptz IS NULL OR e.recorded_at > $6::timestamptz) AND ($7::timestamptz IS NULL OR e.recorded_at <= $7::timestamptz)
      AND ($8::text[] IS NULL OR e.subject_key = ANY($8::text[])) AND ($9::bigint IS NULL OR e.id < $9::bigint)
      AND NOT EXISTS (SELECT 1 FROM belief_events h WHERE h.source_id = e.source_id AND h.subject_kind = e.subject_kind AND h.subject_key = e.subject_key
        AND h.event_type = 'derived.hidden' AND h.id <> e.id AND (h.id > e.id OR e.origin = 'backfill'))
    ORDER BY e.id ${q.descending ? 'DESC' : 'ASC'} LIMIT $5`, [q.sourceId, q.slug ?? null, q.subjectKey ?? null, q.afterId ?? 0, Math.min(Math.max(q.limit ?? 1000, 1), 10_000),
      q.recordedAfter ?? null, q.recordedUntil ?? null, q.subjectKeys ? [...q.subjectKeys] : null, q.beforeId ?? null]);
  const json = (v: unknown) => typeof v === 'string' ? JSON.parse(v) : v;
  const out = rows.map(r => ({ ...r, id: Number(r.id), value: json(r.value) as BeliefHistoryRow['value'], cause: json(r.cause) as BeliefHistoryRow['cause'] }));
  const page = (kept: typeof out) => ({ rows: kept.map(({ stream_visible: _, later_private: __, take_holder: ___, ...row }) => row), scanned: out.length, lastScannedId: out.at(-1)?.id ?? null });
  if (!q.remote) return page(out);
  const linkIds = [...new Set(out.filter(r => r.subject_kind === 'link' || r.subject_kind === 'link_transition').flatMap(r => linkLifetimes(r.subject_key)))];
  const visibleLifetimes = new Set(linkIds.length ? (await engine.executeRaw<{ page_lifetime: string }>(`SELECT l.page_lifetime::text AS page_lifetime
    FROM belief_page_lifetimes l JOIN pages p ON p.source_id = l.source_id AND p.slug = l.slug AND p.deleted_at IS NULL AND (l.page_id IS NULL OR p.id = l.page_id)
    WHERE l.page_lifetime = ANY($1::uuid[]) AND l.ended_at IS NULL AND ${remoteReadFloorSql('p')}`, [linkIds])).map(r => r.page_lifetime) : []);
  const holders = new Set(q.takesHolders ?? ['world']);
  return page(out.filter(r => r.visibility === 'world' && r.later_private !== true
    && (r.subject_kind !== 'take' || typeof r.take_holder === 'string' && holders.has(r.take_holder))
    && (r.page_lifetime == null ? r.subject_kind === 'fact' : r.stream_visible === true)
    && (r.subject_kind !== 'link' && r.subject_kind !== 'link_transition' || linkLifetimes(r.subject_key).every(id => visibleLifetimes.has(id)))));
}