Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.9 KB
Raw Blame
/**
 * Tier changes outside a publication diff (docs/designs/BELIEF_LEDGER.md
 * sections 6.3 and 6.4). A publication or owner action whose tier change lies
 * in its own streams is recorded by its batch's diff. Two writers change tiers
 * of rows in streams they do not publish:
 *
 * - bulk runs (`trust backfill`, `claim-sources --relower`) append one summary
 *   `trust.retiered` per source and stream page, plus one
 *   `belief_retier_manifest` row (subject key, from, to) per changed subject,
 *   keyed by the summary event, so replay can say which belief's trust changed;
 * - derived propagation appends one `trust.retiered` per lowered dependent
 *   outside the enclosing batch's streams, whose cause names each input and
 *   the event that recorded its change; a dependent inside them is recorded
 *   by the batch's diff, at its final state hash, with that cause.
 *
 * Neither holds its dependents' page keys (a lock taken late can deadlock), so
 * these events order within a stream by the row locks the tier UPDATE took.
 */
import { randomUUID } from 'node:crypto';
import type { BrainEngine } from '../engine.ts';
import { readManagedMode } from '../persistence/managed-mode.ts';
import { appendBeliefEvents, type BeliefEventDraft } from './append.ts';
import { eventKeyHex, pageKey, slugRef } from './keys.ts';
import { coverageActive, currentBeliefBatch, noteBelief, readLedgerSource, stateHashOf } from './ledger.ts';
import { resolveLifetimes } from './lifetimes.ts';
import { readBeliefState, type RawPage } from './state.ts';
import { keyedSubjects, pageNeeds } from './subjects.ts';

export interface RetierRow { table: string; id: number; from: string | null; to: string }

interface Resolved {
  row: RetierRow; sourceId: string; incarnation: string; stream: string; page: RawPage | null; lifetime: string | null;
  kind: 'page' | 'fact' | 'take'; key: string; visibility: string; claimFp: string | null; stateHash: string; writerTier: string | null;
}

const KIND: Record<string, 'page' | 'fact' | 'take'> = { pages: 'page', facts: 'fact', takes: 'take' };

/** Each ledger subject among `rows` (timeline rows are not subjects), keyed as its stream's current state keys it; covered sources only. */
async function resolveSubjects(tx: BrainEngine, rows: readonly RetierRow[]): Promise<Resolved[]> {
  const subjects = rows.filter(r => KIND[r.table]);
  if (!subjects.length) return [];
  const ids = (table: string) => subjects.filter(r => r.table === table).map(r => r.id);
  const located = await tx.executeRaw<{ t: string; id: number; source_id: string; slug: string | null }>(`
    SELECT 'facts' AS t, id, source_id, COALESCE(source_markdown_slug, entity_slug) AS slug FROM facts WHERE id = ANY($1::bigint[])
    UNION ALL SELECT 'takes', t.id, p.source_id, p.slug FROM takes t JOIN pages p ON p.id = t.page_id WHERE t.id = ANY($2::bigint[])
    UNION ALL SELECT 'pages', id, source_id, slug FROM pages WHERE id = ANY($3::bigint[])`, [ids('facts'), ids('takes'), ids('pages')]);
  const where = new Map(located.filter(r => r.slug).map(r => [`${r.t}:${Number(r.id)}`, { sourceId: r.source_id, slug: r.slug! }]));
  const out: Resolved[] = [];
  for (const sourceId of new Set([...where.values()].map(w => w.sourceId))) {
    const source = await readLedgerSource(tx, sourceId);
    if (!source || !coverageActive(source.coverage)) continue;
    const mine = subjects.filter(r => where.get(`${r.table}:${r.id}`)?.sourceId === sourceId);
    const streams = [...new Set(mine.map(r => where.get(`${r.table}:${r.id}`)!.slug))];
    const state = await readBeliefState(tx, sourceId, streams);
    const lifetimes = await resolveLifetimes(tx, pageNeeds(sourceId, source.incarnation, state));
    const pagesBySlug = new Map(state.pages.map(p => [p.slug, p]));
    const keyed = keyedSubjects({ incarnation: source.incarnation, lifetimes, pagesBySlug }, state,
      id => state.pages.find(p => p.id === id)?.visible === false ? 'private' : 'world');
    const hash = (slug: string) => { const page = pagesBySlug.get(slug) ?? null; return stateHashOf(page, page ? lifetimes.get(page.id)! : null, keyed.filter(s => s.stream === slug)); };
    for (const row of mine) {
      const stream = where.get(`${row.table}:${row.id}`)!.slug;
      const page = pagesBySlug.get(stream) ?? null;
      const lifetime = page ? lifetimes.get(page.id) ?? null : null;
      const base = { row, sourceId, incarnation: source.incarnation, stream, page, lifetime, stateHash: hash(stream), writerTier: state.writerTier };
      if (row.table === 'pages') {
        if (page && lifetime) out.push({ ...base, kind: 'page', key: pageKey(lifetime), visibility: page.visible ? 'world' : 'private', claimFp: null });
        continue;
      }
      const subject = keyed.find(s => s.kind === KIND[row.table] && s.rowIds.includes(row.id));
      if (subject) out.push({ ...base, kind: subject.kind as 'fact' | 'take', key: subject.key, visibility: subject.visibility, claimFp: subject.claimFp });
    }
  }
  return out;
}

const draftOf = (r: Resolved, cause: Record<string, unknown>): BeliefEventDraft => ({ sourceId: r.sourceId, incarnation: r.incarnation, lifetime: r.lifetime, slug: r.stream,
  stream: r.stream, subjectKind: r.kind, subjectKey: r.key, eventType: 'trust.retiered', trustTier: r.row.to, writerTier: r.writerTier, tierBasis: 'row',
  visibility: r.visibility, value: { from: r.row.from, to: r.row.to }, stateHash: r.stateHash, claimFp: r.claimFp, cause });

/**
 * Per-subject `trust.retiered` events for rows whose tier changed (derived
 * propagation). Appended under the enclosing batch's publication when there is
 * one, else under `publicationId`. Returns the publication id when it appended.
 */
export async function appendRetierEvents(tx: BrainEngine, rows: readonly RetierRow[], cause: Record<string, unknown>, publicationId?: string): Promise<string | null> {
  const batch = currentBeliefBatch();
  const all = await resolveSubjects(tx, rows);
  // A dependent in the enclosing batch's own streams is recorded by its finalization (after every write, with the final state hash); the batch carries the cause.
  const inBatch = (r: Resolved) => !!batch && batch.sourceId === r.sourceId && batch.slugs.includes(r.stream);
  for (const r of all.filter(inBatch)) noteBelief({ kind: 'retier_cause', table: r.row.table as 'facts' | 'takes' | 'pages', rowId: r.row.id, cause });
  const resolved = all.filter(r => !inBatch(r));
  if (!resolved.length) return null;
  const pub = batch?.publicationId ?? publicationId ?? randomUUID();
  let appended = 0;
  for (const sourceId of new Set(resolved.map(r => r.sourceId))) {
    const source = (await readLedgerSource(tx, sourceId))!;
    appended += await appendBeliefEvents(tx, resolved.filter(r => r.sourceId === sourceId).map(r => draftOf(r, cause)),
      { publicationId: pub, origin: await readManagedMode(tx) ? 'live' : 'unmanaged', purgesPossible: source.purgesPossible });
  }
  return appended ? pub : null;
}

/**
 * A bulk run's tier changes in one transaction: one summary `trust.retiered`
 * per source and stream (the stream page's key, or the slug form for a stream
 * with no page) and one manifest row per changed subject. Returns the
 * publication id when it appended.
 */
export async function appendBulkRetier(tx: BrainEngine, rows: readonly RetierRow[], op: string, publicationId = randomUUID()): Promise<string | null> {
  const resolved = await resolveSubjects(tx, rows.filter(r => r.from !== r.to));
  if (!resolved.length) return null;
  let appended = 0;
  for (const sourceId of new Set(resolved.map(r => r.sourceId))) {
    const source = (await readLedgerSource(tx, sourceId))!;
    const mine = resolved.filter(r => r.sourceId === sourceId);
    const summaries = [...new Set(mine.map(r => r.stream))].map(stream => {
      const members = mine.filter(r => r.stream === stream);
      const first = members[0]!;
      const to: Record<string, number> = {};
      for (const m of members) to[m.row.to] = (to[m.row.to] ?? 0) + 1;
      const draft: BeliefEventDraft = { sourceId, incarnation: first.incarnation, lifetime: first.lifetime, slug: stream, stream, subjectKind: 'page',
        subjectKey: first.lifetime ? pageKey(first.lifetime) : JSON.stringify(['p', slugRef(first.incarnation, stream)]), eventType: 'trust.retiered',
        trustTier: first.page?.tier ?? 'unknown', writerTier: first.writerTier, tierBasis: first.page ? 'row' : 'unknown',
        visibility: first.page && !first.page.visible ? 'private' : 'world', value: { summary: true, subjects: members.length, to }, stateHash: first.stateHash,
        cause: { op, manifest: true } };
      return { draft, members };
    });
    appended += await appendBeliefEvents(tx, summaries.map(s => s.draft), { publicationId, origin: await readManagedMode(tx) ? 'live' : 'unmanaged', purgesPossible: source.purgesPossible });
    const manifest = summaries.flatMap(({ draft, members }) => members.map(m => ({ event_key: eventKeyHex(publicationId, draft.subjectKey, draft.eventType),
      subject_kind: m.kind, subject_key: m.key, from_tier: m.row.from, to_tier: m.row.to })));
    await tx.executeRaw(`INSERT INTO belief_retier_manifest (summary_event, source_id, subject_kind, subject_key, from_tier, to_tier)
      SELECT e.id, $1, m.subject_kind, m.subject_key, m.from_tier, m.to_tier
      FROM jsonb_to_recordset($2::text::jsonb) AS m(event_key text, subject_kind text, subject_key text, from_tier text, to_tier text)
      JOIN belief_events e ON e.event_key = decode(m.event_key, 'hex')
      ON CONFLICT DO NOTHING`, [sourceId, JSON.stringify(manifest)]);
  }
  return appended ? publicationId : null;
}

/**
 * The event that recorded each input's tier change, for a propagation's cause:
 * the enclosing batch's own `trust.retiered` when the input lies in its
 * streams (its key is derived, it is appended at finalization), else the
 * newest per-subject event or bulk summary naming the input's key.
 */
export async function retierInputCauses(tx: BrainEngine, inputs: readonly { table: string; id: number }[]): Promise<Array<{ subject_key: string; event_key: string | null }>> {
  const resolved = await resolveSubjects(tx, inputs.map(i => ({ ...i, from: null, to: '' })));
  const batch = currentBeliefBatch();
  const out: Array<{ subject_key: string; event_key: string | null }> = [];
  for (const r of resolved) {
    if (batch && batch.sourceId === r.sourceId && batch.slugs.includes(r.stream)) {
      out.push({ subject_key: r.key, event_key: eventKeyHex(batch.publicationId, r.key, 'trust.retiered') });
      continue;
    }
    const [row] = await tx.executeRaw<{ key: string }>(`SELECT encode(k.event_key, 'hex') AS key FROM (
        SELECT e.id, e.event_key FROM belief_events e WHERE e.source_id = $1 AND e.subject_key = $2 AND e.event_type = 'trust.retiered'
        UNION ALL SELECT e.id, e.event_key FROM belief_retier_manifest m JOIN belief_events e ON e.id = m.summary_event
          WHERE m.source_id = $1 AND m.subject_key = $2) k ORDER BY k.id DESC LIMIT 1`, [r.sourceId, r.key]);
    out.push({ subject_key: r.key, event_key: row?.key ?? null });
  }
  return out;
}